Adicionar dados personalizados aos usuários usando extensões abertas

Neste tutorial, você enxuta como usar extensões abertas.

Imagine que você está criando um aplicativo que está disponível em várias plataformas de cliente, como área de trabalho e móvel. Você deseja permitir que os usuários configurem sua experiência de interface do usuário para que seja consistente, não importa qual dispositivo eles usem para entrar em seu aplicativo.

Para este cenário, este artigo mostra como:

• Represente algumas informações de perfil roaming sobre o usuário usando extensões abertas.
• Consultar o usuário e retornar o perfil móvel.
• Altere as informações de perfil de roaming do usuário armazenadas na extensão aberta.
• Excluir informações do perfil móvel do usuário.

Observação

Além dos usuários, também há suporte para extensões abertas e podem ser gerenciadas para outros tipos de recursos.

Pré-requisitos

Para reproduzir as etapas deste artigo, você precisa dos seguintes privilégios:

• Entre em um cliente de API, como o Graph Explorer e o usuário para o qual você deseja armazenar o perfil de roaming.
• Conceda ao aplicativo a permissão delegada User.ReadWrite para o usuário conectado.

Etapa 1. Adicionar informações de perfil roaming

O usuário entra no aplicativo e configura a aparência do aplicativo. Essas configurações de aplicativo devem transitar para que o usuário obtenha a mesma experiência em praticamente qualquer dispositivo usado para entrar no aplicativo. O aplicativo chama o Microsoft Graph executando a solicitação a seguir para adicionar as informações de perfil roaming ao objeto de recurso do usuário conectado.

Solicitação

HTTP

POST https://graph.microsoft.com/v1.0/me/extensions
Content-type: application/json

{
    "@odata.type":"microsoft.graph.openTypeExtension",
    "extensionName":"com.contoso.roamingSettings",
    "theme":"dark",
    "color":"purple",
    "lang":"Japanese"
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new OpenTypeExtension
{
	OdataType = "microsoft.graph.openTypeExtension",
	ExtensionName = "com.contoso.roamingSettings",
	AdditionalData = new Dictionary<string, object>
	{
		{
			"theme" , "dark"
		},
		{
			"color" , "purple"
		},
		{
			"lang" , "Japanese"
		},
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Extensions.PostAsync(requestBody);

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

CLI

mgc users extensions create --user-id {user-id} --body '{\
    "@odata.type":"microsoft.graph.openTypeExtension",\
    "extensionName":"com.contoso.roamingSettings",\
    "theme":"dark",\
    "color":"purple",\
    "lang":"Japanese"\
}\
'

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Ir

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewExtension()
extensionName := "com.contoso.roamingSettings"
requestBody.SetExtensionName(&extensionName) 
additionalData := map[string]interface{}{
	"theme" : "dark", 
	"color" : "purple", 
	"lang" : "Japanese", 
}
requestBody.SetAdditionalData(additionalData)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
extensions, err := graphClient.Me().Extensions().Post(context.Background(), requestBody, nil)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

OpenTypeExtension extension = new OpenTypeExtension();
extension.setOdataType("microsoft.graph.openTypeExtension");
extension.setExtensionName("com.contoso.roamingSettings");
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("theme", "dark");
additionalData.put("color", "purple");
additionalData.put("lang", "Japanese");
extension.setAdditionalData(additionalData);
Extension result = graphClient.me().extensions().post(extension);

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const extension = {
    '@odata.type':'microsoft.graph.openTypeExtension',
    extensionName: 'com.contoso.roamingSettings',
    theme: 'dark',
    color: 'purple',
    lang: 'Japanese'
};

await client.api('/me/extensions')
	.post(extension);

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\OpenTypeExtension;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new OpenTypeExtension();
$requestBody->setOdataType('microsoft.graph.openTypeExtension');
$requestBody->setExtensionName('com.contoso.roamingSettings');
$additionalData = [
	'theme' => 'dark',
	'color' => 'purple',
	'lang' => 'Japanese',
];
$requestBody->setAdditionalData($additionalData);

$result = $graphServiceClient->me()->extensions()->post($requestBody)->wait();

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

PowerShell

Import-Module Microsoft.Graph.Users

$params = @{
	"@odata.type" = "microsoft.graph.openTypeExtension"
	extensionName = "com.contoso.roamingSettings"
	theme = "dark"
	color = "purple"
	lang = "Japanese"
}

# A UPN can also be used as -UserId.
New-MgUserExtension -UserId $userId -BodyParameter $params

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.open_type_extension import OpenTypeExtension
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = OpenTypeExtension(
	odata_type = "microsoft.graph.openTypeExtension",
	extension_name = "com.contoso.roamingSettings",
	additional_data = {
			"theme" : "dark",
			"color" : "purple",
			"lang" : "Japanese",
	}
)

result = await graph_client.me.extensions.post(request_body)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Resposta

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('376bdbfc-e41f-4082-a8cf-b31731465eeb')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "extensionName": "com.contoso.roamingSettings",
    "theme": "dark",
    "color": "purple",
    "lang": "Japanese",
    "id": "com.contoso.roamingSettings"
}

Etapa 2. Recuperar informações de perfil roaming

Quando o usuário entra no aplicativo de outro dispositivo, o aplicativo chama o Microsoft Graph para recuperar os detalhes do perfil do usuário e expandir a propriedade de navegação de extensões para obter suas configurações de roaming, em seguida, usa esses dados para fornecer a mesma experiência que no outro dispositivo.

Solicitação

HTTP

GET https://graph.microsoft.com/v1.0/me?$select=id,displayName,mail,mobilePhone&$expand=extensions

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "id","displayName","mail","mobilePhone" };
	requestConfiguration.QueryParameters.Expand = new string []{ "extensions" };
});

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

CLI

mgc users get --user-id {user-id} --select "id,displayName,mail,mobilePhone" --expand "extensions"

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Ir

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

requestParameters := &graphusers.MeRequestBuilderGetQueryParameters{
	Select: [] string {"id","displayName","mail","mobilePhone"},
	Expand: [] string {"extensions"},
}
configuration := &graphusers.MeRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
me, err := graphClient.Me().Get(context.Background(), configuration)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.me().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"id", "displayName", "mail", "mobilePhone"};
	requestConfiguration.queryParameters.expand = new String []{"extensions"};
});

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/me')
	.expand('extensions')
	.select('id,displayName,mail,mobilePhone')
	.get();

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Me\MeRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UserItemRequestBuilderGetRequestConfiguration();
$queryParameters = UserItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["id","displayName","mail","mobilePhone"];
$queryParameters->expand = ["extensions"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->get($requestConfiguration)->wait();

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

PowerShell

Import-Module Microsoft.Graph.Users

# A UPN can also be used as -UserId.
Get-MgUser -UserId $userId -Property "id,displayName,mail,mobilePhone" -ExpandProperty "extensions" 

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.me.me_request_builder import MeRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MeRequestBuilder.MeRequestBuilderGetQueryParameters(
		select = ["id","displayName","mail","mobilePhone"],
		expand = ["extensions"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.get(request_configuration = request_configuration)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Resposta

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,mail,mobilePhone,extensions())/$entity",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET me?$select=signInActivity,accountEnabled",
    "id": "376bdbfc-e41f-4082-a8cf-b31731465eeb",
    "displayName": "Raul Razo",
    "mail": null,
    "mobilePhone": null,
    "extensions@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('376bdbfc-e41f-4082-a8cf-b31731465eeb')/extensions",
    "extensions": [
        {
            "@odata.type": "#microsoft.graph.openTypeExtension",
            "extensionName": "com.contoso.roamingSettings",
            "theme": "dark",
            "color": "purple",
            "lang": "Japanese",
            "id": "com.contoso.roamingSettings"
        }
    ]
}

Etapa 3. Alterar informações de perfil roaming

O usuário pode optar por alterar suas informações de perfil roaming. O aplicativo chama o Microsoft Graph executando a consulta a seguir. A solicitação retorna o código de resposta 204 No Content.

Você também deve incluir todas as propriedades no corpo da solicitação, mesmo que queira atualizar apenas um subconjunto delas. Caso contrário, o Microsoft Graph remove as propriedades que você não passa. Para excluir dados, mas manter uma propriedade, defina o valor da propriedade como null.

HTTP

PATCH https://graph.microsoft.com/v1.0/me/extensions/com.contoso.roamingSettings
Content-type: application/json

{
    "theme":"light",
    "color":"yellow",
    "lang":"Swahili"
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Extension
{
	AdditionalData = new Dictionary<string, object>
	{
		{
			"theme" , "light"
		},
		{
			"color" , "yellow"
		},
		{
			"lang" , "Swahili"
		},
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Extensions["{extension-id}"].PatchAsync(requestBody);

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

CLI

mgc users extensions patch --user-id {user-id} --extension-id {extension-id} --body '{\
    "theme":"light",\
    "color":"yellow",\
    "lang":"Swahili"\
}\
'

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Ir

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewExtension()
additionalData := map[string]interface{}{
	"theme" : "light", 
	"color" : "yellow", 
	"lang" : "Swahili", 
}
requestBody.SetAdditionalData(additionalData)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
extensions, err := graphClient.Me().Extensions().ByExtensionId("extension-id").Patch(context.Background(), requestBody, nil)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Extension extension = new Extension();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("theme", "light");
additionalData.put("color", "yellow");
additionalData.put("lang", "Swahili");
extension.setAdditionalData(additionalData);
Extension result = graphClient.me().extensions().byExtensionId("{extension-id}").patch(extension);

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const extension = {
    theme: 'light',
    color: 'yellow',
    lang: 'Swahili'
};

await client.api('/me/extensions/com.contoso.roamingSettings')
	.update(extension);

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Extension;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Extension();
$additionalData = [
	'theme' => 'light',
	'color' => 'yellow',
	'lang' => 'Swahili',
];
$requestBody->setAdditionalData($additionalData);

$result = $graphServiceClient->me()->extensions()->byExtensionId('extension-id')->patch($requestBody)->wait();

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

PowerShell

Import-Module Microsoft.Graph.Users

$params = @{
	theme = "light"
	color = "yellow"
	lang = "Swahili"
}

# A UPN can also be used as -UserId.
Update-MgUserExtension -UserId $userId -ExtensionId $extensionId -BodyParameter $params

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.extension import Extension
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Extension(
	additional_data = {
			"theme" : "light",
			"color" : "yellow",
			"lang" : "Swahili",
	}
)

result = await graph_client.me.extensions.by_extension_id('extension-id').patch(request_body)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Etapa 4. Excluir o perfil de roaming de um usuário

O usuário decide que não deseja mais um perfil de roaming. Para excluir a propriedade de extensão, o aplicativo chama o Microsoft Graph executando a solicitação a seguir. A solicitação retorna o código de resposta 204 No Content.

HTTP

DELETE https://graph.microsoft.com/v1.0/me/extensions/com.contoso.roamingSettings

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Me.Extensions["{extension-id}"].DeleteAsync();

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

CLI

mgc users extensions delete --user-id {user-id} --extension-id {extension-id}

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Ir

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Me().Extensions().ByExtensionId("extension-id").Delete(context.Background(), nil)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

graphClient.me().extensions().byExtensionId("{extension-id}").delete();

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

await client.api('/me/extensions/com.contoso.roamingSettings')
	.delete();

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$graphServiceClient->me()->extensions()->byExtensionId('extension-id')->delete()->wait();

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

PowerShell

Import-Module Microsoft.Graph.Users

# A UPN can also be used as -UserId.
Remove-MgUserExtension -UserId $userId -ExtensionId $extensionId

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

await graph_client.me.extensions.by_extension_id('extension-id').delete()

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Conteúdo relacionado

• Adicionar dados personalizados a recursos usando extensões
• Adicionar dados personalizados a grupos usando as extensões do esquema
• tipo de recurso openTypeExtension