Общие сведения об 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 см. в разделе:
- Автоматизация подготовки и отзыва пользователей в приложениях SaaS с помощью Microsoft Entra ID
- Управление подготовкой учетных записей пользователей для корпоративных приложений в Центр администрирования Microsoft Entra
Вы также можете попробовать 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": []
}