使用 Graph Explorer 进行 API 驱动的入站预配快速入门

2025-04-30

本教程介绍如何使用 Microsoft Graph 资源管理器快速测试 API 驱动的入站预配。

先决条件

你配置了 API 驱动的入站预配应用。

注意

此预配 API 主要在应用程序或服务内使用。租户管理员可以配置服务主体或托管标识，以授予执行上传的权限。此 API 没有单独的用户可分配Microsoft Entra 内置目录角色。除了获得 SynchronizationData-User.Upload 管理员许可权限的应用程序之外，具有用户管理员角色的管理员用户可以调用 API。本教程介绍如何在测试设置中使用用户管理员角色测试 API。

将用户数据上传到入站预配 API

打开新的浏览器选项卡或浏览器窗口。
启动 URL https://aka.ms/ge 以访问 Microsoft Graph Explorer。
选择用户头像图标以登录。
使用具有用户管理员角色访问权限的用户帐户完成登录过程。
成功登录后，租户信息会显示租户名称。

现在可以调用 API 了。
在 API 请求面板中，将 HTTP 请求类型设置为 POST。
复制并粘贴从预配应用概述页检索到的预配 API 终结点。
在“请求标头”面板下，添加新的 Content-Type = application/scim+json 键值对。
在 “请求正文 ”面板下，使用 SCIM 企业用户架构复制粘贴批量请求
选择“ 运行查询 ”按钮，将请求发送到预配 API 终结点。
如果请求成功发送，你将从 API 终结点获取 Accepted 202 响应。
打开 “响应标头 ”面板并复制位置属性的 URL 值。这指向预配日志 API 终结点，可以查询该终结点以检查批量请求中存在的用户的预配状态。

验证批量请求有效负载的处理

请求正文

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
    {
        "method": "POST",
        "bulkId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
            "externalId": "701984",
            "userName": "bjensen@example.com",
            "name": {
                "formatted": "Ms. Barbara J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Barbara",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Babs Jensen",
            "nickName": "Babs",
            "emails": [
            {
              "value": "bjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "100 Universal City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91608",
              "country": "USA",
              "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5555",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Guide",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                 "employeeNumber": "701984",
                 "costCenter": "4130",
                 "organization": "Universal Studios",
                 "division": "Theme Park",
                 "department": "Tour Operations",
                 "manager": {
                     "value": "89607",
                     "displayName": "John Smith"
                 }
            }
        }
    },
    {
        "method": "POST",
        "bulkId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
            "externalId": "701985",
            "userName": "Kjensen@example.com",
            "name": {
                "formatted": "Ms. Kathy J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Kathy",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Kathy Jensen",
            "nickName": "Kathy",
            "emails": [
            {
              "value": "kjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "100 Oracle City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91618",
              "country": "USA",
              "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5545",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Lead",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                 "employeeNumber": "701985",
                 "costCenter": "4130",
                 "organization": "Universal Studios",
                 "division": "Theme Park",
                 "department": "Tour Operations",
                 "manager": {
                     "value": "701984",
                     "displayName": "Barbara Jensen"
                 }
            }
        }
    }
],
    "failOnErrors": null
}

可以从 Microsoft Entra 管理中心或使用 Graph Explorer 验证处理。

从 Microsoft Entra 管理中心验证处理

至少使用应用程序管理员登录凭据登录到 Microsoft Entra 管理中心。
浏览到 Entra ID>企业应用。
在所有应用程序下，使用搜索筛选器文本框查找并打开 API 驱动的预配应用程序。
打开“预配”边栏选项卡。登陆页面会显示上次运行的状态。
选择 “查看预配日志” 以打开“预配日志”窗格。或者，可以选择“ 监视>预配日志”菜单选项。
选择预配日志中的任何记录以查看其他处理详细信息。
预配日志详细信息屏幕显示为特定用户执行的所有步骤。
- 在“从 API 导入”步骤下，查看从批量请求中提取的用户数据的详细信息。
- “匹配用户”步骤显示基于匹配标识符的任何用户匹配的详细信息。如果有用户匹配，则预配服务将执行更新操作。如果没有用户匹配项，配置服务将执行创建操作。
- “确定用户是否在范围内”步骤显示范围筛选器评估的详细信息。默认情况下，将处理所有用户。如果设置范围筛选器（例如，仅处理属于销售部门的用户），则范围筛选器的评估详细信息将显示在此步骤中。
- “预配用户”步骤会调用最终处理步骤和应用于用户帐户的更改。
- 使用“修改的属性”选项卡可以查看属性更新。

在 Graph Explorer 中使用预配日志 API 验证处理

可以使用作为预配 API 调用中的位置响应头的一部分返回的预配日志 API URL 来检查处理。

在 Graph 资源管理器中， “请求 URL ”文本框复制粘贴预配 API 终结点返回的位置 URL，也可以使用格式构造该 URL： https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid eq '<jobId>' 可从预配应用概述页中检索 jobId 位置 URL。
使用 GET 方法 并选择 “运行查询 ”检索预配日志。默认情况下，返回的响应包含所有日志记录。
可以将更多筛选器设置为仅在特定时间范围后检索数据，或检索具有特定状态值的数据。 https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid eq '<jobId> and statusInfo/status eq 'failure' and activityDateTime ge 2022-10-10T09:47:34Z 还可以按源系统中使用的 externalId 值来检查用户的状态，该值用作源定位点/联接属性。 https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid eq '<jobId>' and sourceIdentity/id eq '701984'

附录

使用 SCIM 企业用户架构的批量请求

以下批量请求使用 SCIM 标准核心用户和企业用户架构。