Konfigurieren der Synchronisierung mit Verzeichniserweiterungsattributen

Artikel
02/07/2024

Namespace: microsoft.graph

Sie können Ihr Synchronisierungsschema anpassen, um Microsoft Entra Verzeichniserweiterungsattribute einzuschließen. In diesem Artikel wird beschrieben, wie Sie ein Verzeichniserweiterungsattribut (extension_9d98asdfl15980a_Nickname) verwenden, um den Wert von User.CommunityNickname in Salesforce aufzufüllen. In diesem Szenario haben Sie Microsoft Entra Connect eingerichtet, um eine Reihe von Verzeichniserweiterungsattributen von Windows Server Active Directory lokal in Microsoft Entra ID bereitzustellen.

In diesem Artikel wird davon ausgegangen, dass Sie bereits eine Anwendung hinzugefügt haben, die die Synchronisierung mit Ihrem Mandanten über die Microsoft Entra Admin Center unterstützt, dass Sie den Anzeigenamen der Anwendung kennen und über ein Autorisierungstoken für Microsoft Graph verfügen. Informationen zum Abrufen des Autorisierungstokens finden Sie unter Abrufen von Zugriffstoken zum Aufrufen von Microsoft Graph.

Suchen des Dienstprinzipalobjekts anhand des Anzeigenamens

Das folgende Beispiel zeigt, wie Sie ein Dienstprinzipalobjekt mit dem Anzeigenamen "Salesforce Sandbox" finden.

Anforderung

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


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



mgc service-principals list --filter "startswith(displayName, 'salesforce')" --select "id,appId,displayName"



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

// Dependencies
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
)

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,
}

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


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


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


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


Import-Module Microsoft.Graph.Applications

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


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.service_principals.service_principals_request_builder import ServicePrincipalsRequestBuilder
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 = ServicePrincipalsRequestBuilder.ServicePrincipalsRequestBuilderGetQueryParameters(
		select = ["id","appId","displayName"],
		filter = "startswith(displayName, 'salesforce')",
)

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


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

Antwort

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

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

Auflisten von Synchronisierungsaufträgen im Kontext des Dienstprinzipals

Im folgenden Beispiel wird gezeigt, wie Sie die abrufen, mit der jobId Sie arbeiten müssen. Im Allgemeinen gibt die Antwort nur einen Auftrag zurück.

Anforderung

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


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



mgc service-principals synchronization jobs list --service-principal-id {servicePrincipal-id}



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

// Dependencies
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
)

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

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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
jobs, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Synchronization().Jobs().Get(context.Background(), configuration)


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


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


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


Import-Module Microsoft.Graph.Applications

Get-MgServicePrincipalSynchronizationJob -ServicePrincipalId $servicePrincipalId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.service_principals.item.synchronization.jobs.jobs_request_builder import JobsRequestBuilder
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

request_configuration = RequestConfiguration()
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)

Antwort

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

Der {jobId} ist SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa.

Suchen sie den Namen des verzeichniserweiterungsattributs, das Sie benötigen.

Sie benötigen den vollständigen Namen des Erweiterungsattributs. Wenn Sie den vollständigen Namen nicht kennen (der in etwa wie extension_9d98asdfl15980a_Nickname aussehen sollte), lesen Sie die folgenden Informationen zu Verzeichniserweiterungsattributen und deren Untersuchung:

Abrufen des Synchronisierungsschemas

Das folgende Beispiel zeigt, wie Sie das Synchronisierungsschema abrufen.

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


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



mgc service-principals synchronization jobs schema get --service-principal-id {servicePrincipal-id} --synchronization-job-id {synchronizationJob-id}



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

// Dependencies
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
)

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

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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
schema, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Synchronization().Jobs().BySynchronizationJobId("synchronizationJob-id").Schema().Get(context.Background(), configuration)


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


const options = {
	authProvider,
};

const client = Client.init(options);

let synchronizationSchema = await client.api('/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/schema')
	.header('Authorization','Bearer {Token}')
	.get();


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


Import-Module Microsoft.Graph.Applications

Get-MgServicePrincipalSynchronizationJobSchema -ServicePrincipalId $servicePrincipalId -SynchronizationJobId $synchronizationJobId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.service_principals.item.synchronization.jobs.item.schema.schema_request_builder import SchemaRequestBuilder
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

request_configuration = RequestConfiguration()
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)

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

Hinzufügen einer Definition für das Verzeichniserweiterungsattribut und einer Zuordnung zwischen den Attributen

Verwenden Sie einen Nur-Text-Editor Ihrer Wahl (z. B. Editor++ oder JSON Editor Online), um:

Fügen Sie eine Attributdefinition für das extension_9d98asdfl15980a_Nickname Attribut hinzu.
- Suchen Sie unter Verzeichnisse nach dem Verzeichnis mit dem Namen "Microsoft Entra ID", und suchen Sie im Array des Objekts nach dem Verzeichnis mit dem Namen User.
- Fügen Sie der Liste das neue Attribut hinzu, und geben Sie dabei den Namen und Typ an, wie im folgenden Beispiel gezeigt.

Fügen Sie eine Attributzuordnung zwischen extension_9d98asdfl15980a_Nickname und CommunityNickname hinzu.

Suchen Sie unter synchronizationRules die Regel, die Microsoft Entra ID als Quellverzeichnis angibt, und Salesforce.com als Zielverzeichnis ("sourceDirectoryName": "Azure Active Directory", "targetDirectoryName": "salesforce.com").
Suchen Sie in objectMappings der Regel nach der Zuordnung zwischen Benutzern ("sourceObjectName": "User", "targetObjectName": "User").
Fügen Sie im attributMappings-Array von objectMapping einen neuen Eintrag hinzu, wie im folgenden Beispiel gezeigt.

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

Speichern des geänderten Synchronisierungsschemas

Stellen Sie beim Speichern des aktualisierten Synchronisierungsschemas sicher, dass Sie das gesamte Schema einschließlich der unveränderten Teile einschließen. Diese Anforderung ersetzt das vorhandene Schema durch das von Ihnen bereitgestellte Schema.

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

Wenn das Schema erfolgreich gespeichert wurde, gibt die Anforderung einen 204 No Content Antwortcode zurück. Bei der nächsten Iteration des Synchronisierungsauftrags beginnt er mit der erneuten Verarbeitung aller Konten in Ihrem Microsoft Entra ID, und die neuen Zuordnungen werden auf alle bereitgestellten Konten angewendet.

Übersicht über die Microsoft Entra ID-Synchronisierungs-API

Freigeben über

Konfigurieren der Synchronisierung mit Verzeichniserweiterungsattributen

Suchen des Dienstprinzipalobjekts anhand des Anzeigenamens

Anforderung

Antwort

Auflisten von Synchronisierungsaufträgen im Kontext des Dienstprinzipals

Anforderung

Antwort

Suchen sie den Namen des verzeichniserweiterungsattributs, das Sie benötigen.

Abrufen des Synchronisierungsschemas

Hinzufügen einer Definition für das Verzeichniserweiterungsattribut und einer Zuordnung zwischen den Attributen

Speichern des geänderten Synchronisierungsschemas

Feedback

Zusätzliche Ressourcen

Freigeben über

Konfigurieren der Synchronisierung mit Verzeichniserweiterungsattributen

Suchen des Dienstprinzipalobjekts anhand des Anzeigenamens

Anforderung

Antwort

Auflisten von Synchronisierungsaufträgen im Kontext des Dienstprinzipals

Anforderung

Antwort

Suchen sie den Namen des verzeichniserweiterungsattributs, das Sie benötigen.

Abrufen des Synchronisierungsschemas

Hinzufügen einer Definition für das Verzeichniserweiterungsattribut und einer Zuordnung zwischen den Attributen

Speichern des geänderten Synchronisierungsschemas

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen