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

  • Статья

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

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

Microsoft Entra синхронизация удостоверений (также называемая "подготовка") позволяет автоматизировать подготовку (создание, обслуживание) и отмену подготовки (удаление) удостоверений из любого из следующих объектов:

  • Active Directory для Microsoft Entra ID
  • От рабочего дня до Microsoft Entra ID
  • Microsoft Entra ID к облачным приложениям, таким как Dropbox, Salesforce, ServiceNow и т. д.

Можно воспользоваться интерфейсами API синхронизации в Microsoft Graph для управления синхронизацией удостоверений программными средствами, в том числе для:

  • создания, запуска и остановки заданий синхронизации
  • изменения схемы синхронизации для заданий
  • проверки текущего состояния синхронизации

Дополнительные сведения о синхронизации в Microsoft Entra ID см. в разделе:

Вы также можете попробовать API в Обозреватель Graph в примере клиента или собственного клиента.

Задание синхронизации

Задания синхронизации выполняют синхронизацию, периодически выполняя в фоновом режиме, опрашивая изменения в одном каталоге и отталкивая их в другой каталог. Задание синхронизации всегда зависит от конкретного экземпляра приложения в клиенте. В рамках настройки задания синхронизации необходимо предоставить разрешение на чтение и запись объектов в целевом каталоге, а также настроить схему синхронизации задания.

Дополнительные сведения см. в разделе Задание синхронизации.

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

Схема синхронизации определяет, какие объекты будут синхронизированы и как они будут синхронизированы. Схема синхронизации содержит большую часть сведений о настройке для определенного задания синхронизации. Как правило, вы настраиваете некоторые сопоставления атрибутов или добавляете фильтр области для синхронизации только объектов, удовлетворяющих определенному условию.

Схема синхронизации включает следующие компоненты:

  • Определения каталогов
  • Правила синхронизации
  • Сопоставления объектов

Дополнительные сведения см. в разделе Схема синхронизации.

Шаблон синхронизации

Шаблон синхронизации предоставляет предварительно настроенные параметры синхронизации для определенного приложения. Эти параметры (самое главное, схема синхронизации) будут использоваться по умолчанию для любого задания синхронизации , основанного на шаблоне. Шаблоны задаются разработчиком приложения.

Дополнительные сведения см. в разделе Шаблон синхронизации.

Работа с API синхронизации

Работа с API синхронизации в основном включает доступ к ресурсам synchronizationJob и synchronizationSchema . Чтобы найти ресурс synchronizationJob , необходимо знать идентификатор объекта субъекта-службы, которому принадлежит задание синхронизации. В следующих примерах показано, как работать с ресурсами synchronizationJob и synchronizationSchema .

Авторизация

Для работы с API синхронизации Microsoft Entra Microsoft Graph поддерживает следующие детализированные разрешения:

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

И следующие Microsoft Entra роли каталога:

  • Администратор приложения
  • Администратор облачного приложения
  • Администратор гибридных удостоверений
  • Глобальный администратор

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

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

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

Запрос

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

Отклик

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

Поиск объекта субъекта-службы по идентификатору приложения

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

Запрос

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

Отклик

HTTP/1.1 200 OK

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

Список существующих заданий синхронизации

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

Запрос

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

Отклик

HTTP/1.1 200 OK

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

Получение состояния задания синхронизации

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

Запрос

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

Отклик

HTTP/1.1 200 OK

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

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

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

Запрос

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

Отклик

HTTP/1.1 200 OK

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

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