Configurer la synchronisation avec les attributs d’extension d’annuaire

Espace de noms: microsoft.graph

Vous pouvez personnaliser votre schéma de synchronisation pour inclure Microsoft Entra attributs d’extension d’annuaire. Cet article explique comment utiliser un attribut d’extension d’annuaire (extension_9d98asdfl15980a_Nickname) pour remplir la valeur de User.CommunityNickname dans Salesforce. Dans ce scénario, vous avez configuré Microsoft Entra Connect pour provisionner un certain nombre d’attributs d’extension d’annuaire de Windows Server Active Directory local vers Microsoft Entra ID.

Cet article part du principe que vous avez déjà ajouté une application qui prend en charge la synchronisation avec votre locataire via le centre d'administration Microsoft Entra, que vous connaissez le nom complet de l’application et que vous disposez d’un jeton d’autorisation pour Microsoft Graph. Pour plus d’informations sur la façon d’obtenir le jeton d’autorisation, consultez Obtenir des jetons d’accès pour appeler Microsoft Graph.

Rechercher l’objet principal de service par nom d’affichage

L’exemple suivant montre comment rechercher un objet principal de service avec le nom complet « Salesforce Sandbox ».

Demande

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

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

CLI

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

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (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)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (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}");
});

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (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();

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (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();

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PowerShell

Import-Module Microsoft.Graph.Applications

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

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Python

from msgraph import GraphServiceClient
from msgraph.generated.service_principals.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)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Réponse

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

est {servicePrincipalId}60443998-8cf7-4e61-b05c-a53b658cb5e1.

Répertorier les travaux de synchronisation dans le contexte du principal de service

L’exemple suivant vous montre comment obtenir le jobId que vous devez utiliser. En règle générale, la réponse ne retourne qu’un seul travail.

Demande

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

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

CLI

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

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (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)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (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}");
});

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (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();

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (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();

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PowerShell

Import-Module Microsoft.Graph.Applications

Get-MgServicePrincipalSynchronizationJob -ServicePrincipalId $servicePrincipalId

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Python

from msgraph import GraphServiceClient
from msgraph.generated.service_principals.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)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Réponse

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

est {jobId}SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa.

Rechercher le nom de l’attribut d’extension d’annuaire dont vous avez besoin

Vous aurez besoin du nom complet de l’attribut d’extension. Si vous ne connaissez pas le nom complet (qui doit ressembler à extension_9d98asdfl15980a_Nickname), consultez les informations suivantes sur les attributs d’extension d’annuaire et la façon de les inspecter :

• Extension du schéma d’annuaire Microsoft Entra avec des propriétés personnalisées
• Extensions de schéma d’annuaire | API Graph concepts

Obtenir le schéma de synchronisation

L’exemple suivant montre comment obtenir le schéma de synchronisation.

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

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (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}

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (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)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (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}");
});

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (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();

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (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();

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PowerShell

Import-Module Microsoft.Graph.Applications

Get-MgServicePrincipalSynchronizationJobSchema -ServicePrincipalId $servicePrincipalId -SynchronizationJobId $synchronizationJobId

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Python

from msgraph import GraphServiceClient
from msgraph.generated.service_principals.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)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité. Toutes les propriétés seront retournées dans un appel réel.

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

Ajouter une définition pour l’attribut d’extension d’annuaire et un mappage entre les attributs

Utilisez un éditeur de texte brut de votre choix (par exemple, Bloc-notes++ ou JSON Rédacteur Online) pour :

1. Ajoutez une définition d’attribut pour l’attribut extension_9d98asdfl15980a_Nickname .

   • Sous répertoires, recherchez le répertoire nommé « Microsoft Entra ID » et, dans le tableau de l’objet, recherchez celui nommé Utilisateur.
   • Ajoutez le nouvel attribut à la liste, en spécifiant le nom et le type, comme illustré dans l’exemple suivant.

2. Ajoutez un mappage d’attribut entre extension_9d98asdfl15980a_Nickname et CommunityNickname.

   • Sous synchronizationRules, recherchez la règle qui spécifie Microsoft Entra ID comme répertoire source et Salesforce.com comme répertoire cible ("sourceDirectoryName": "Azure Active Directory", "targetDirectoryName": "salesforce.com").
   • Dans objectMappings de la règle, recherchez le mappage entre les utilisateurs ("sourceObjectName": "User", "targetObjectName": "User").
   • Dans le tableau attributeMappings de l’objetMapping, ajoutez une nouvelle entrée, comme illustré dans l’exemple suivant.

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

Enregistrer le schéma de synchronisation modifié

Lorsque vous enregistrez le schéma de synchronisation mis à jour, veillez à inclure l’intégralité du schéma, y compris les parties non modifiées. Cette demande remplace le schéma existant par celui que vous fournissez.

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

Si le schéma a été enregistré avec succès, la requête retourne un 204 No Content code de réponse. Lors de la prochaine itération du travail de synchronisation, il commencera à rétraiter tous les comptes de votre Microsoft Entra ID, et les nouveaux mappages seront appliqués à tous les comptes provisionnés.

Contenu connexe

• Vue d’ensemble de l’API de synchronisation Microsoft Entra ID