Настройка синхронизации с атрибутами расширения каталога

Пространство имен: microsoft.graph

Схему синхронизации можно настроить так, чтобы она включала Microsoft Entra атрибуты расширения каталога. В этой статье описывается использование атрибута расширения каталога (extension_9d98asdfl15980a_Nickname) для заполнения значения User.CommunityNickname в Salesforce. В этом сценарии Microsoft Entra Connect настроено для подготовки ряда атрибутов расширения каталога из Windows Server Active Directory локальной среды в Microsoft Entra ID.

В этой статье предполагается, что вы уже добавили приложение, которое поддерживает синхронизацию с клиентом через Центр администрирования Microsoft Entra, знаете отображаемое имя приложения и что у вас есть маркер авторизации для Microsoft Graph. Сведения о том, как получить маркер авторизации, см. в статье Получение маркеров доступа для вызова Microsoft Graph.

Поиск объекта субъекта-службы по отображаемого имени

В следующем примере показано, как найти объект субъекта-службы с отображаемым именем Salesforce Sandbox.

Запрос

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}");
});

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

CLI

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

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Go

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)

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

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}");
});

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

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();

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

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();

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

PowerShell

Import-Module Microsoft.Graph.Applications

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

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

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)

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Отклик

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"
    }
    ]
}

Имеет {servicePrincipalId} значение 60443998-8cf7-4e61-b05c-a53b658cb5e1.

Вывод списка заданий синхронизации в контексте субъекта-службы

В следующем примере показано, как получить jobId объект , с которым необходимо работать. Как правило, ответ возвращает только одно задание.

Запрос

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}");
});

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc service-principals synchronization jobs list --service-principal-id {servicePrincipal-id}

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Go

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)

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

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}");
});

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

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();

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

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();

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

PowerShell

Import-Module Microsoft.Graph.Applications

Get-MgServicePrincipalSynchronizationJob -ServicePrincipalId $servicePrincipalId

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

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)

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Отклик

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": {}
    }
    ]
}

Имеет {jobId} значение SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa.

Найдите имя необходимого атрибута расширения каталога.

Вам потребуется полное имя атрибута расширения. Если вы не знаете полное имя (которое должно выглядеть как extension_9d98asdfl15980a_Nickname), ознакомьтесь со следующими сведениями об атрибутах расширения каталога и их проверке:

• Расширение схемы каталога Microsoft Entra пользовательскими свойствами
• Расширения схемы каталогов | основные понятия API Graph

Получение схемы синхронизации

В следующем примере показано, как получить схему синхронизации.

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}");
});

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

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}

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Go

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)

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

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}");
});

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

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();

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

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();

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

PowerShell

Import-Module Microsoft.Graph.Applications

Get-MgServicePrincipalSynchronizationJobSchema -ServicePrincipalId $servicePrincipalId -SynchronizationJobId $synchronizationJobId

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

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)

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости. Все свойства будут возвращены в фактическом вызове.

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"
        }
      ]
    }
  ]
}

Добавьте определение атрибута расширения каталога и сопоставление между атрибутами.

Используйте редактор обычного текста по своему выбору (например, Блокнот++ или JSON Редактор Online), чтобы:

1. Добавьте определение атрибута для атрибута extension_9d98asdfl15980a_Nickname .

   • В разделе каталоги найдите каталог с именем "Microsoft Entra ID", а в массиве объекта найдите каталог с именем User.
   • Добавьте новый атрибут в список, указав имя и тип, как показано в следующем примере.

2. Добавьте сопоставление атрибутов между extension_9d98asdfl15980a_Nickname и CommunityNickname.

   • В разделе synchronizationRules найдите правило, указывающее Microsoft Entra ID в качестве исходного каталога, а Salesforce.com в качестве целевого каталога ("sourceDirectoryName": "Azure Active Directory", "targetDirectoryName": "salesforce.com").
   • В objectMappings правила найдите сопоставление между пользователями ("sourceObjectName": "User", "targetObjectName": "User").
   • В массиве attributeMappingsобъекта objectMapping добавьте новую запись, как показано в следующем примере.

   {
       "directories": [
           {
               "id": "66e4a8cc-1b7b-435e-95f8-f06cea133828",
               "name": "Azure Active Directory",
               "objects": [
                   {
                       "attributes": [
                               ,{
                               "name": "extension_9d98asdfl15980a_Nickname",
                               "type": "String"
                               }
                       ],
                       "name":"User"
                   }]
           }
       ],
       "synchronizationRules": [
           {
           "editable": true,
           "id": "4c5ecfa1-a072-4460-b1c3-4adde3479854",
           "metadata": [..],
           "name": "USER_OUTBOUND_USER",
           "objectMappings": [
               {
                   "attributeMappings": [
                   ,{
                       "source": {
                           "name": "extension_9d98asdfl15980a_Nickname",
                           "type": "Attribute"
                       },
                       "targetAttributeName": "CommunityNickname"
                       }
               ],
               "name": "Synchronize Azure Active Directory Users to salesforce.com",
                   "scope": null,
                   "sourceObjectName": "User",
                   "targetObjectName": "User"
               }
           ],
           "priority": 1,
           "sourceDirectoryName": "Azure Active Directory",
           "targetDirectoryName": "salesforce.com"
           },
       ]
   }
   

Сохранение измененной схемы синхронизации

При сохранении обновленной схемы синхронизации убедитесь, что вы включили всю схему, включая неизмененные части. Этот запрос заменит существующую схему указанной схемой.

PUT https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/schema
Authorization: Bearer {Token}
{
    "directories": [],
    "synchronizationRules": []
}

Если схема была успешно сохранена, запрос возвращает 204 No Content код ответа. При следующей итерации задания синхронизации начнется повторная обработка всех учетных записей в Microsoft Entra ID, а новые сопоставления будут применены ко всем подготовленным учетным записям.

Связанные материалы

• Общие сведения об API синхронизации Microsoft Entra ID