Configurar a sincronização com atributos de destino personalizados

Namespace: microsoft.graph

Você pode personalizar seu esquema de sincronização para incluir atributos personalizados definidos no diretório de destino. Este artigo descreve como personalizar uma assinatura do Salesforce adicionando um novo campo chamado officeCode. Você configura a sincronização de Microsoft Entra ID para o Salesforce e, para cada usuário, preencherá o officeCode campo no Salesforce com o valor do extensionAttribute10 campo em Microsoft Entra ID.

Este artigo pressupõe que você já tenha adicionado um aplicativo que dá suporte à sincronização ao locatário por meio do centro de administração do Microsoft Entra, que você conhece o nome da exibição do aplicativo e que tem um token de autorização para o Microsoft Graph. Para obter informações sobre como obter o token de autorização, consulte Obter tokens de acesso para chamar o Microsoft Graph.

Localizar o objeto da entidade de serviço por nome de exibição

O exemplo a seguir mostra como encontrar um objeto de entidade de serviço com o nome de exibição Salesforce.

Solicitação

HTTP

GET https://graph.microsoft.com/v1.0/servicePrincipals?$select=id,appId,displayName&$filter=startswith(displayName, 'salesforce')
Authorization: Bearer {Token}

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.ServicePrincipals.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "id","appId","displayName" };
	requestConfiguration.QueryParameters.Filter = "startswith(displayName, 'salesforce')";
	requestConfiguration.Headers.Add("Authorization", "Bearer {Token}");
});

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

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc service-principals list --filter "startswith(displayName, 'salesforce')" --select "id,appId,displayName"

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

import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphserviceprincipals "github.com/microsoftgraph/msgraph-sdk-go/serviceprincipals"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


headers := abstractions.NewRequestHeaders()
headers.Add("Authorization", "Bearer {Token}")


requestFilter := "startswith(displayName, 'salesforce')"

requestParameters := &graphserviceprincipals.ServicePrincipalsRequestBuilderGetQueryParameters{
	Select: [] string {"id","appId","displayName"},
	Filter: &requestFilter,
}
configuration := &graphserviceprincipals.ServicePrincipalsRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

servicePrincipals, err := graphClient.ServicePrincipals().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);

ServicePrincipalCollectionResponse result = graphClient.servicePrincipals().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"id", "appId", "displayName"};
	requestConfiguration.queryParameters.filter = "startswith(displayName, 'salesforce')";
	requestConfiguration.headers.add("Authorization", "Bearer {Token}");
});

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 servicePrincipals = await client.api('/servicePrincipals')
	.header('Authorization','Bearer {Token}')
	.filter('startswith(displayName, \'salesforce\')')
	.select('id,appId,displayName')
	.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\ServicePrincipals\ServicePrincipalsRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new ServicePrincipalsRequestBuilderGetRequestConfiguration();
$headers = [
		'Authorization' => 'Bearer {Token}',
	];
$requestConfiguration->headers = $headers;

$queryParameters = ServicePrincipalsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["id","appId","displayName"];
$queryParameters->filter = "startswith(displayName, 'salesforce')";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->servicePrincipals()->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.Applications

Get-MgServicePrincipal -Property "id,appId,displayName" -Filter "startswith(displayName, 'salesforce')" 

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

from msgraph import GraphServiceClient
from msgraph.generated.servicePrincipals.service_principals_request_builder import ServicePrincipalsRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = ServicePrincipalsRequestBuilder.ServicePrincipalsRequestBuilderGetQueryParameters(
		select = ["id","appId","displayName"],
		filter = "startswith(displayName, 'salesforce')",
)

request_configuration = ServicePrincipalsRequestBuilder.ServicePrincipalsRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("Authorization", "Bearer {Token}")


result = await graph_client.service_principals.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#servicePrincipals(id,appId,displayName)",
    "value": [
    {
        "id": "167e33e9-f80e-490e-b4d8-698d4a80fb3e",
        "appId": "cd3ed3de-93ee-400b-8b19-b61ef44a0f29",
        "displayName": "Salesforce"
    },
    {
        "id": "8cbbb70b-7290-42da-83ee-89fa3517a977",
        "appId": "b0f2e3b1-fe31-4658-b216-44dcaeabb63a",
        "displayName": "salesforce 1"
    },
    {
        "id": "60443998-8cf7-4e61-b05c-a53b658cb5e1",
        "appId": "79079396-c301-405d-900f-e2e0c2439a90",
        "displayName": "Salesforce Sandbox"
    }
    ]
}

O {servicePrincipalId} é 167e33e9-f80e-490e-b4d8-698d4a80fb3e.

Listar trabalhos de sincronização no contexto da entidade de serviço

O exemplo a seguir mostra como obter o com o jobId qual você precisa trabalhar. Geralmente, a resposta retorna apenas um trabalho.

Solicitação

HTTP

GET https://graph.microsoft.com/v1.0/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs
Authorization: Bearer {Token}

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.ServicePrincipals["{servicePrincipal-id}"].Synchronization.Jobs.GetAsync((requestConfiguration) =>
{
	requestConfiguration.Headers.Add("Authorization", "Bearer {Token}");
});

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

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc service-principals synchronization jobs list --service-principal-id {servicePrincipal-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

import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphserviceprincipals "github.com/microsoftgraph/msgraph-sdk-go/serviceprincipals"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


headers := abstractions.NewRequestHeaders()
headers.Add("Authorization", "Bearer {Token}")

configuration := &graphserviceprincipals.ServicePrincipalItemSynchronizationJobsRequestBuilderGetRequestConfiguration{
	Headers: headers,
}

jobs, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Synchronization().Jobs().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);

SynchronizationJobCollectionResponse result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").synchronization().jobs().get(requestConfiguration -> {
	requestConfiguration.headers.add("Authorization", "Bearer {Token}");
});

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 jobs = await client.api('/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs')
	.header('Authorization','Bearer {Token}')
	.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\ServicePrincipals\Item\Synchronization\Jobs\JobsRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new JobsRequestBuilderGetRequestConfiguration();
$headers = [
		'Authorization' => 'Bearer {Token}',
	];
$requestConfiguration->headers = $headers;


$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->synchronization()->jobs()->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.Applications

Get-MgServicePrincipalSynchronizationJob -ServicePrincipalId $servicePrincipalId

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

from msgraph import GraphServiceClient
from msgraph.generated.servicePrincipals.item.synchronization.jobs.jobs_request_builder import JobsRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)


request_configuration = JobsRequestBuilder.JobsRequestBuilderGetRequestConfiguration()
request_configuration.headers.add("Authorization", "Bearer {Token}")


result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').synchronization.jobs.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#servicePrincipals('60443998-8cf7-4e61-b05c-a53b658cb5e1')/synchronization/jobs",
    "value": [
        {
            "id": "SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa",
            "templateId": "SfSandboxOutDelta",
            "schedule": {},
            "status": {}
    }
    ]
}

O {jobId} é SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa.

Obter o esquema de sincronização

O exemplo a seguir mostra como obter o esquema de sincronização.

HTTP

GET https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/schema
Authorization: Bearer {Token}

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.ServicePrincipals["{servicePrincipal-id}"].Synchronization.Jobs["{synchronizationJob-id}"].Schema.GetAsync((requestConfiguration) =>
{
	requestConfiguration.Headers.Add("Authorization", "Bearer {Token}");
});

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

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc service-principals synchronization jobs schema get --service-principal-id {servicePrincipal-id} --synchronization-job-id {synchronizationJob-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

import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphserviceprincipals "github.com/microsoftgraph/msgraph-sdk-go/serviceprincipals"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


headers := abstractions.NewRequestHeaders()
headers.Add("Authorization", "Bearer {Token}")

configuration := &graphserviceprincipals.ServicePrincipalItemSynchronizationJobItemSchemaRequestBuilderGetRequestConfiguration{
	Headers: headers,
}

schema, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Synchronization().Jobs().BySynchronizationJobId("synchronizationJob-id").Schema().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);

SynchronizationSchema result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").synchronization().jobs().bySynchronizationJobId("{synchronizationJob-id}").schema().get(requestConfiguration -> {
	requestConfiguration.headers.add("Authorization", "Bearer {Token}");
});

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 synchronizationSchema = await client.api('/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/schema')
	.header('Authorization','Bearer {Token}')
	.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\ServicePrincipals\Item\Synchronization\Jobs\Item\Schema\SchemaRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new SchemaRequestBuilderGetRequestConfiguration();
$headers = [
		'Authorization' => 'Bearer {Token}',
	];
$requestConfiguration->headers = $headers;


$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->synchronization()->jobs()->bySynchronizationJobId('synchronizationJob-id')->schema()->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.Applications

Get-MgServicePrincipalSynchronizationJobSchema -ServicePrincipalId $servicePrincipalId -SynchronizationJobId $synchronizationJobId

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

from msgraph import GraphServiceClient
from msgraph.generated.servicePrincipals.item.synchronization.jobs.item.schema.schema_request_builder import SchemaRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)


request_configuration = SchemaRequestBuilder.SchemaRequestBuilderGetRequestConfiguration()
request_configuration.headers.add("Authorization", "Bearer {Token}")


result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').synchronization.jobs.by_synchronization_job_id('synchronizationJob-id').schema.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 .

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade. Todas as propriedades serão retornadas em uma chamada real.

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

{
  "directories": [
    {
      "id": "66e4a8cc-1b7b-435e-95f8-f06cea133828",
      "name": "Azure Active Directory",
      "objects": [
        {
          "attributes": [
            {
              "anchor": true,
              "caseExact": false,
              "defaultValue": null,
              "metadata": [],
              "multivalued": false,
              "mutability": "ReadWrite",
              "name": "objectId",
              "required": false,
              "referencedObjects": [],
              "type": "String"
            },
            {
              "anchor": false,
              "caseExact": false,
              "defaultValue": null,
              "metadata": [],
              "multivalued": false,
              "mutability": "ReadWrite",
              "name": "streetAddress",
              "required": false,
              "referencedObjects": [],
              "type": "String"
            }
          ],
          "name": "User"
        }
      ]
    },
    {
      "id": "8ffa6169-f354-4751-9b77-9c00765be92d",
      "name": "salesforce.com",
      "objects": []
    }
  ],
  "synchronizationRules": [
    {
      "editable": true,
      "id": "4c5ecfa1-a072-4460-b1c3-4adde3479854",
      "name": "USER_OUTBOUND_USER",
      "objectMappings": [
        {
          "attributeMappings": [
            {
              "defaultValue": "True",
              "exportMissingReferences": false,
              "flowBehavior": "FlowWhenChanged",
              "flowType": "Always",
              "matchingPriority": 0,
              "source": {
                "expression": "Not([IsSoftDeleted])",
                "name": "Not",
                "parameters": [
                  {
                    "key": "source",
                    "value": {
                      "expression": "[IsSoftDeleted]",
                      "name": "IsSoftDeleted",
                      "parameters": [],
                      "type": "Attribute"
                    }
                  }
                ],
                "type": "Function"
              },
              "targetAttributeName": "IsActive"
            }
          ],
          "enabled": true,
          "flowTypes": "Add, Update, Delete",
          "name": "Synchronize Azure Active Directory Users to salesforce.com",
          "scope": null,
          "sourceObjectName": "User",
          "targetObjectName": "User"
        }
      ]
    }
  ]
}

Adicionar uma definição para o atributo officeCode e um mapeamento entre atributos

Use um editor de texto simples de sua escolha (por exemplo, Notepad++ ou JSON Editor Online) para:

1. Adicione uma definição de atributo para o officeCode atributo.

   • Em diretórios, localize o diretório com o nome salesforce.com e, na matriz do objeto, localize o chamado Usuário.
   • Adicione o novo atributo à lista, especificando o nome e o tipo, conforme mostrado no exemplo a seguir.

2. Adicione um mapeamento de atributo entre officeCode e extensionAttribute10.

   • Em synchronizationRules, localize a regra que especifica Microsoft Entra ID como o diretório de origem e Salesforce.com como o diretório de destino ("sourceDirectoryName": "Azure Active Directory", "targetDirectoryName": "salesforce.com").
   • Nos objectMappings da regra, localize o mapeamento entre usuários ("sourceObjectName": "User", "targetObjectName": "User").
   • Na matriz attributeMappings do objectMapping, adicione uma nova entrada, conforme mostrado no exemplo a seguir.

{  
    "directories": [
    {
        "id": "8ffa6169-f354-4751-9b77-9c00765be92d",
            "name": "salesforce.com",
            "objects": [
            {
                "attributes": [
                        {
                            "name": "officeCode",
                            "type": "String"
                        }
                ],
                "name":"User"
            }]
    }
    ],
    "synchronizationRules": [
        {
        "editable": true,
        "id": "4c5ecfa1-a072-4460-b1c3-4adde3479854",
        "name": "USER_OUTBOUND_USER",
        "objectMappings": [
            {
            "attributeMappings": [
                {
                    "source": {
                            "name": "extensionAttribute10",
                            "type": "Attribute"
                        },
                    "targetAttributeName": "officeCode"
                }
            ],
            "name": "Synchronize Azure Active Directory Users to salesforce.com",
            "scope": null,
            "sourceObjectName": "User",
            "targetObjectName": "User"
            }
        ],
    "priority": 1,
        "sourceDirectoryName": "Azure Active Directory",
        "targetDirectoryName": "salesforce.com"
    }
    ]
}

Salvar o esquema de sincronização modificado

Ao salvar o esquema de sincronização atualizado, certifique-se de incluir todo o esquema, incluindo as partes não modificadas. Essa solicitação substituirá o esquema existente pelo que você fornece.

HTTP

PUT https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/schema
Authorization: Bearer {Token}

{
    "directories": [..],
    "synchronizationRules": [..]
}

C#

Snippet not available

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

Snippet not available

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

Snippet not available

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

Snippet not available

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 synchronizationSchema = {
    directories: [..],
    synchronizationRules: [..]
};

await client.api('/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/schema')
	.put(synchronizationSchema);

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

Snippet not available

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

Snippet not available

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

Snippet not available

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

Se o esquema foi salvo com êxito, a solicitação retornará um código de 204 No Content resposta. Na próxima iteração do trabalho de sincronização, ele começará a reprocessar todas as contas em seu Microsoft Entra ID e os novos mapeamentos serão aplicados a todas as contas provisionadas.

Conteúdo relacionado

• visão geral da API de sincronização Microsoft Entra ID