Microsoft Entra ID同步 API 概述

  • 项目

命名空间：microsoft.graph

Microsoft Entra标识同步 (也称为“预配”) 允许自动执行预配 (创建、维护) 和取消预配 (删除) 以下任何标识：

  • 要Microsoft Entra ID的 Active Directory
  • Workday to Microsoft Entra ID
  • Microsoft Entra ID到 Dropbox、Salesforce、ServiceNow 等云应用程序

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

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

有关Microsoft Entra ID同步的详细信息，请参阅：

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

同步作业

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

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

同步架构

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

同步架构包括以下组件：

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

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

同步模板

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

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

使用同步 API

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

Authorization

若要使用Microsoft Entra ID同步 API，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/v1.0/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/v1.0/servicePrincipals(appId='219561ee-1480-4c67-9aa6-63d861fae3ef')?$select=id,appId,displayName

响应

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/v1.0/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/v1.0/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/v1.0/servicePrincipals/{id}/synchronization/jobs/{jobId}/schema

响应

HTTP/1.1 200 OK

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

相关内容