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

  • Artikel

Namespace: microsoft.graph

Microsoft Entra Identitätssynchronisierung (auch als "Bereitstellung" bezeichnet) können Sie die Bereitstellung (Erstellung, Wartung) und Aufhebung der Bereitstellung (Entfernung) von Identitäten aus einer der folgenden Komponenten automatisieren:

  • Active Directory Microsoft Entra ID
  • Workday to Microsoft Entra ID
  • Microsoft Entra ID zu Cloudanwendungen wie Dropbox, Salesforce, ServiceNow und mehr

Sie können die Synchronisierungs-APIs in Microsoft Graph verwenden, um die Synchronisierung der Identitäten programmgesteuert zu verwalten, einschließlich:

  • Erstellen, Starten und Beenden von Synchronisierungsaufträgen
  • Vornehmen von Änderungen am Synchronisierungsschema für Aufträge
  • Überprüfen des aktuellen Synchronisierungsstatus

Weitere Informationen zur Synchronisierung in Microsoft Entra ID finden Sie unter:

Sie können die API auch im Graph-Explorer in einem Beispielmandanten oder Ihrem eigenen Mandanten ausprobieren.

Synchronisierungsauftrag

Synchronisierungsaufträge führen die Synchronisierung durch, indem sie regelmäßig im Hintergrund ausgeführt werden, um Änderungen in einem Verzeichnis abzufragen und sie in ein anderes Verzeichnis zu pushen. Der Synchronisierungsauftrag ist immer spezifisch für einen bestimmten instance einer Anwendung in Ihrem Mandanten. Im Rahmen der Einrichtung des Synchronisierungsauftrags müssen Sie die Berechtigung zum Lesen und Schreiben von Objekten in Ihrem Zielverzeichnis erteilen und das Synchronisierungsschema des Auftrags anpassen.

Weitere Informationen finden Sie unter Synchronisierungsauftrag.

Synchronisierungsschema

Das Synchronisierungsschema definiert, welche Objekte synchronisiert werden und wie sie synchronisiert werden. Das Synchronisierungsschema enthält die meisten Setupinformationen für einen bestimmten Synchronisierungsauftrag. In der Regel passen Sie einige attributbasierte Zuordnungen an oder fügen einen Bereichsfilter hinzu, um nur Objekte zu synchronisieren, die eine bestimmte Bedingung erfüllen.

Das Synchronisierungsschema enthält die folgenden Komponenten:

  • Verzeichnisdefinitionen
  • Synchronisierungsregeln
  • Objektzuordnungen

Weitere Informationen finden Sie unter Synchronisierungsschema.

Synchronisierungsvorlage

Die Synchronisierungsvorlage stellt vorkonfigurierte Synchronisierungseinstellungen für eine bestimmte Anwendung bereit. Diese Einstellungen (vor allem das Synchronisierungsschema) werden standardmäßig für jeden Synchronisierungsauftrag verwendet, der auf der Vorlage basiert. Vorlagen werden vom Anwendungsentwickler angegeben.

Weitere Informationen finden Sie unter Synchronisierungsvorlage.

Arbeiten mit der Synchronisierungs-API

Das Arbeiten mit der Synchronisierungs-API umfasst in erster Linie den Zugriff auf die SynchronizationJob- und synchronizationSchema-Ressourcen. Um Ihre synchronizationJob-Ressource zu finden, müssen Sie die ID des Dienstprinzipalobjekts kennen, zu dem der Synchronisierungsauftrag gehört. In den folgenden Beispielen wird gezeigt, wie Sie mit den SynchronizationJob - und synchronizationSchema-Ressourcen arbeiten.

Authorization

Um mit den Microsoft Entra ID-Synchronisierungs-APIs zu arbeiten, unterstützt Microsoft Graph die folgenden differenzierten Berechtigungen:

  • Synchronization.Read.All
  • Synchronization.ReadWrite.All
  • Application.ReadWrite.OwnedBy
  • Application.Read.All
  • Application.ReadWrite.All

Und die folgenden Microsoft Entra Rollen:

  • Anwendungsadministrator
  • Cloudanwendungsadministrator
  • Hybrididentitätsadministrator
  • Globaler Administrator

Weitere Informationen zu den Berechtigungen, die Sie zum Aufrufen der einzelnen APIs benötigen, finden Sie in der entsprechenden API-Referenzdokumentation.

Suchen des Dienstprinzipalobjekts anhand des Anzeigenamens

Das folgende Beispiel zeigt, wie Sie das Dienstprinzipalobjekt anhand des Anzeigenamens suchen.

Anforderung

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

Antwort

HTTP/1.1 200 OK

{
   "value":[
      {
         "id":"bc0dc311-87df-48ac-91b1-259bd2c3a31c",
         "appId":"f7808c5e-cb57-4e37-8094-406d302c0f8d",
         "displayName":"Salesforce"
      },
      {
         "id":"d813d7d7-0f41-4edc-b284-d0dfaf399d15",
         "appId":"219561ee-1480-4c67-9aa6-63d861fae3ef",
         "displayName":"salesforce 3"
      }
   ]
}

Suchen des Dienstprinzipalobjekts nach App-ID

Das folgende Beispiel zeigt, wie Sie das Dienstprinzipalobjekt nach App-ID suchen.

Anforderung

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='219561ee-1480-4c67-9aa6-63d861fae3ef')?$select=id,appId,displayName

Antwort

HTTP/1.1 200 OK

{
    "value": [
        {
            "id": "d813d7d7-0f41-4edc-b284-d0dfaf399d15",
            "appId": "219561ee-1480-4c67-9aa6-63d861fae3ef",
            "displayName": "salesforce 3"
        }
    ]
}

Auflisten vorhandener Synchronisierungsaufträge

Im folgenden Beispiel wird gezeigt, wie Sie vorhandene Synchronisierungsaufträge auflisten.

Anforderung

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

Antwort

HTTP/1.1 200 OK

{
    "value": [
        {
            "id": "SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa",
            "templateId": "SfSandboxOutDelta",
            "schedule": {
                "expiration": null,
                "interval": "PT20M",
                "state": "Active"
            },
            "status": {}
        }
    ]
}

Abrufen von status für Synchronisierungsaufträge

Im folgenden Beispiel wird gezeigt, wie Sie die status eines Synchronisierungsauftrags abrufen.

Anforderung

GET https://graph.microsoft.com/v1.0/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs/SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa

Antwort

HTTP/1.1 200 OK

{
    "id": "SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa",
    "templateId": "SfSandboxOutDelta",
    "schedule": {
        "expiration": null,
        "interval": "PT20M",
        "state": "Active"
    },
    "status": {}
}

Abrufen des Synchronisierungsschemas

Das folgende Beispiel zeigt, wie Sie das Synchronisierungsschema abrufen.

Anforderung

GET https://graph.microsoft.com/v1.0/servicePrincipals/{id}/synchronization/jobs/{jobId}/schema

Antwort

HTTP/1.1 200 OK

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

Verwandte Inhalte