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

  • Article

Espace de noms: microsoft.graph

Importante

Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .

Microsoft Entra synchronisation des identités (également appelée « approvisionnement ») vous permet d’automatiser l’approvisionnement (création, maintenance) et le déprovisionnement (suppression) des identités de l’un des éléments suivants :

  • Active Directory à Microsoft Entra ID
  • Workday à Microsoft Entra ID
  • Microsoft Entra ID aux applications cloud telles que Dropbox, Salesforce, ServiceNow, etc.

Vous pouvez utiliser les API de synchronisation dans Microsoft Graph pour la gestion de la synchronisation d’identité par programme, notamment :

  • Créer, démarrer et stopper des tâches de synchronisation
  • Apporter des modifications au schéma de synchronisation des tâches
  • Vérifier l’état actuel de la synchronisation

Pour plus d’informations sur la synchronisation dans Microsoft Entra ID, consultez :

Vous pouvez également essayer l’API dans l’Explorer Graph dans un exemple de locataire ou dans votre propre locataire.

Travail de synchronisation

Les tâches de synchronisation effectuent la synchronisation en s’exécutant régulièrement en arrière-plan, en interrogeant les modifications dans un répertoire et en les poussant vers un autre répertoire. Le travail de synchronisation est toujours spécifique à un instance particulier d’une application dans votre locataire. Dans le cadre de la configuration du travail de synchronisation, vous devez autoriser la lecture et l’écriture d’objets dans votre répertoire cible, et personnaliser le schéma de synchronisation du travail.

Pour plus d’informations, consultez Travail de synchronisation.

Schéma de synchronisation

Le schéma de synchronisation définit les objets qui seront synchronisés et la façon dont ils seront synchronisés. Le schéma de synchronisation contient la plupart des informations d’installation d’un travail de synchronisation particulier. En règle générale, vous allez personnaliser certains mappages d’attributs ou ajouter un filtre d’étendue pour synchroniser uniquement les objets qui répondent à une certaine condition.

Le schéma de synchronisation comprend les composants suivants :

  • Définitions de répertoires
  • Règles de synchronisation
  • Mappages d’objets

Pour plus d’informations, consultez Schéma de synchronisation.

Modèle de synchronisation

Le modèle de synchronisation fournit des paramètres de synchronisation préconfigurés pour une application particulière. Ces paramètres (le plus important, le schéma de synchronisation) sont utilisés par défaut pour tout travail de synchronisation basé sur le modèle. Les modèles sont spécifiés par le développeur de l’application.

Pour plus d’informations, consultez Modèle de synchronisation.

Utilisation de l’API de synchronisation

L’utilisation de l’API de synchronisation implique principalement l’accès aux ressources synchronizationJob et synchronizationSchema . Pour trouver votre ressource synchronizationJob , vous devez connaître l’ID de l’objet principal de service auquel appartient le travail de synchronisation. Les exemples suivants vous montrent comment utiliser les ressources synchronizationJob et synchronizationSchema .

Autorisation

Pour utiliser les API de synchronisation Microsoft Entra, Microsoft Graph prend en charge les autorisations granulaires suivantes :

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

Et les rôles d’annuaire Microsoft Entra suivants :

  • Administrateur de l'application
  • Administrateur de l'application cloud
  • Administrateur d’identité hybride
  • Administrateur général

Pour plus d’informations sur les privilèges dont vous avez besoin pour appeler chaque API, consultez la documentation de référence sur les API correspondantes.

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

L’exemple suivant montre comment rechercher l’objet principal de service par nom d’affichage.

Demande

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

Réponse

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

Rechercher l’objet principal de service par ID d’application

L’exemple suivant montre comment rechercher l’objet principal de service par ID d’application.

Demande

GET https://graph.microsoft.com/beta/servicePrincipals?$select=id,appId,displayName&$filter=AppId eq '219561ee-1480-4c67-9aa6-63d861fae3ef'

Réponse

HTTP/1.1 200 OK

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

Répertorier les travaux de synchronisation existants

L’exemple suivant montre comment répertorier les travaux de synchronisation existants.

Demande

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs
GET https://graph.microsoft.com/beta/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs

Réponse

HTTP/1.1 200 OK

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

Obtenir les status du travail de synchronisation

L’exemple suivant montre comment obtenir les status d’un travail de synchronisation.

Demande

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}

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

Réponse

HTTP/1.1 200 OK

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

Obtenir le schéma de synchronisation

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

Demande

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

Réponse

HTTP/1.1 200 OK

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

Contenu connexe