Azure AD 同步 API 概述

  • 项目

命名空间：microsoft.graph

重要

Microsoft Graph 中版本下的 /beta API 可能会更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 在 v1.0 中是否可用，请使用 版本 选择器。

Azure Active Directory (Azure AD) 标识同步 (也称为“预配”) 允许自动执行预配 (创建、维护) 和取消预配 (删除) 以下任一项标识：

  • Active Directory 到 Azure AD
  • Workday 到 Azure AD
  • Azure AD 到云应用程序，例如 Dropbox、Salesforce、ServiceNow 等

可使用 Microsoft Graph 中的同步 API 以编程方式管理标识同步，包括：

  • 创建、启动和停止同步作业
  • 对作业的同步架构进行更改
  • 验证当前同步状态

有关 Azure AD 中的同步的详细信息，请参阅：

还可以在示例租户或你自己的租户的 Graph 资源管理器 中试用 API。

同步作业

同步作业通过定期在后台运行、轮询一个目录中的更改并将其推送到另一个目录来执行同步。 同步作业始终特定于租户中应用程序的特定实例。 在同步作业设置过程中，需要授予读取和写入目标目录中对象的授权，并自定义作业的同步架构。

有关详细信息，请参阅 同步作业。

同步架构

同步架构定义将同步哪些对象以及如何同步它们。 同步架构包含特定同步作业的大部分设置信息。 通常，你将自定义某些 属性映射，或添加 范围筛选器 ，以便仅同步满足特定条件的对象。

同步架构包括以下组件：

  • 目录定义
  • 同步规则
  • 对象映射

有关详细信息，请参阅 同步架构。

同步模板

同步模板为特定应用程序提供预配置的同步设置。 这些设置 (最重要的是， 同步架构) 默认用于基于模板的任何 同步作业 。 模板由应用程序开发人员指定。

有关详细信息，请参阅 同步模板。

使用同步 API

使用同步 API 主要涉及访问 synchronizationJob 和 synchronizationSchema 资源。 若要查找 synchronizationJob 资源，需要知道同步作业所属的服务主体对象的 ID。 以下示例演示如何使用 synchronizationJob 和 synchronizationSchema 资源。

授权

Azure AD 同步 API 使用 OAuth 2.0 进行授权。 在向 API 发出任何请求之前，需要获取访问令牌。 有关详细信息，请参阅 获取访问令牌以调用 Microsoft Graph。 若要访问同步资源，应用程序需要 Directory.ReadWrite.All 权限。 有关详细信息，请参阅 目录权限。

按显示名称查找服务主体对象

以下示例演示如何按显示名称查找服务主体对象。

请求

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

按应用 ID 查找服务主体对象

以下示例演示如何按应用 ID 查找服务主体对象。

请求

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

另请参阅