执行 bulkUpload

  • 项目

命名空间：microsoft.graph

使用同步作业执行新的批量上传。 使用此 API 终结点将数据引入Microsoft Entra同步服务。 同步服务应用与同步作业关联的映射并处理传入的数据。 此 API 的速率限制为每秒 40 个请求。 每个请求在批量请求操作数组中最多可以包含 50 个用户 操作 。

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） SynchronizationData-User.Upload 不可用。
委派（个人 Microsoft 帐户） 不支持。 不支持。
应用程序 SynchronizationData-User.Upload 不可用。

注意

此 API 主要用于负责处理权威标识数据并将其上传到Microsoft Entra ID的应用程序或服务中。 租户管理员可以 配置服务主体或托管标识 ，以授予执行上传的权限。 此 API 没有单独的用户可分配Microsoft Entra内置目录角色。 在已获得 SynchronizationData-User.Upload 管理员同意的权限的应用程序之外，只有具有 全局管理员 角色的管理员用户才能调用 API。

HTTP 请求

POST /servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload

在 API 终结点中， {servicePrincipalId} 引用服务主体对象 ID，并 {jobId} 引用预配作业 ID。

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
Content-Type application/scim+json。 必填。

请求正文

在请求正文中，提供 bulkUpload 资源类型。 有关示例有效负载，请参阅 示例 部分。

响应

如果成功，则返回响应， 202 Accepted 且响应正文中不返回任何内容。 它还返回 一个 Location 标头，用于检查批量请求预配的状态。

HTTP 状态代码 解释
202 (接受) 批量请求将暂存执行，并由关联的预配作业进行处理。 Location响应标头中的键指向可用于检查批量请求预配状态的预配日志终结点。
400 (错误的请求) 请求不可分析、语法不正确或违反架构。 此错误的最常见原因是缺少 Content-Type 请求标头。 请确保它存在并将 设置为 application/scim+json。
401 (未经授权的) 授权标头无效或缺失。 确保授权标头具有有效的访问令牌。
403 (禁止) 不允许基于提供的授权标头执行该操作。 请确保 API 客户端具有 SynchronizationData-User.Upload 权限，对于委派方案，调用方必须是全局管理员。

示例

示例 1：使用 SCIM 核心用户和企业用户架构批量上传

请求

以下批量请求使用 SCIM 标准核心用户和企业用户架构。 它在 Operations 数组中具有两个用户操作。 每个批量请求中最多可以发送 50 个用户操作。

处理详细信息： 预配服务读取两条用户记录。 它使用 在预配作业的属性映射中配置的 和 externalId 的匹配属性userName，以确定是在目录中创建、更新、启用或禁用用户帐户。 它使用 manager.value 字段解析管理器引用。 externalId在此字段中指定用户经理的 。 在以下示例中，预配服务将 Barbara Jensen 分配为 Kathy Jensen 的经理。

POST https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload
Authorization: Bearer <token>
Content-Type: application/scim+json

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
    {
        "method": "POST",
        "bulkId": "701984",
        "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": "234300 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": "701985",
        "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": "701984",
              "costCenter": "4130",
              "organization": "Universal Studios",
              "division": "Theme Park",
              "department": "Tour Operations",
              "manager": {
                "value": "701984",
                "displayName": "Barbara Jensen"
              }
            }
        }
    }
],
    "failOnErrors": null
}

响应

注意：为了提高可读性，可能缩短了此处显示的响应对象。

HTTP/1.1 202 Accepted
Content-Type: application/scim+json
client-request-id: 92cd10f6-fcc3-5d61-098e-a6dd35e460ef
content-length: "0"
location: "https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid%20eq%20'API2AAD.b16687d38faf42adb29892cdcaf01c6e.1a03de52-b9c3-4e2c-a1e3-9145aaa8e530'"
request-id: beeb9ea0-f7e4-4fe7-8507-cd834c88f18b

{}

示例 2：使用 SCIM 自定义架构命名空间批量上传

请求

以下批量请求使用 SCIM 标准核心用户和企业用户架构。 它具有另一个名为 的 urn:contoso:employee 自定义架构命名空间，其中包含两个属性 HireDate 和 JobCode。 schemas数据对象中的数组将更新为包含自定义架构命名空间。

处理详细信息： 预配服务读取两条用户记录。 它使用 在预配作业的属性映射中配置的 和 externalId 的匹配属性userName，以确定是在目录中创建、更新、启用或禁用用户帐户。 如果在预配作业属性映射中包含两个自定义属性 urn:contoso:employee:HireDate 和 urn:contoso:employee:JobCode ，则会对其进行处理，并设置相应的目标属性。

POST https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload
Authorization: Bearer <token>
Content-Type: application/scim+json

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
    {
        "method": "POST",
        "bulkId": "701984",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
            "urn:contoso:employee"],
            "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": "234300 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"
                 }
            },
            "urn:contoso:employee": {
                "HireDate": "2021-05-01T00:00:00-05:00",
                "JobCode": "AB-1002"
            }            
        }
    },
    {
        "method": "POST",
        "bulkId": "701985",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
            "urn:contoso:employee"],
            "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": "701984",
              "costCenter": "4130",
              "organization": "Universal Studios",
              "division": "Theme Park",
              "department": "Tour Operations",
              "manager": {
                "value": "701984",
                "displayName": "Barbara Jensen"
             }
            },
            "urn:contoso:employee": {
                "HireDate": "2022-07-15T00:00:00-05:00",
                "JobCode": "AB-1003"
            }            
        }
    }
],
    "failOnErrors": null
}

响应

注意：为了提高可读性，可能缩短了此处显示的响应对象。

HTTP/1.1 202 Accepted
Content-Type: application/scim+json
client-request-id: 92cd10f6-fcc3-5d61-098e-a6dd35e460ef
content-length: "0"
location: "https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid%20eq%20'API2AAD.b16687d38faf42adb29892cdcaf01c6e.1a03de52-b9c3-4e2c-a1e3-9145aaa8e530'"
request-id: beeb9ea0-f7e4-4fe7-8507-cd834c88f18b

{}

示例 3：批量上传以更新现有用户

请求

以下批量请求说明了如何更新现有Microsoft Entra用户的属性、更改用户的部门以及禁用该用户的登录。 此示例假定已为 externalId、部门和活动字段配置映射，并且现有Microsoft Entra用户具有与 externalId 匹配的属性。

POST https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload
Authorization: Bearer <token>
Content-Type: application/scim+json

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
        {
            "method": "POST",
            "bulkId": "7172023",
            "path": "/Users",
            "data": {
                "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
                "externalId": "7172023",
                "active": false,
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                    "department": "Tour Ops"
                }
            }
        }
    ],
    "failOnErrors": null
}

响应

注意：为了提高可读性，可能缩短了此处显示的响应对象。

HTTP/1.1 202 Accepted
Content-Type: application/scim+json
client-request-id: 92cd20f6-fcc3-5d61-098e-a6dd35e460ef
content-length: "0"
location: "https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid%20eq%20'API2AAD.b16687d38faf42adb29892cdcaf01c6e.1a03de52-b9c3-4e2c-a1e3-9145aaa8e530'"
request-id: beec9ea0-f7e4-4fe7-8507-cd834c88f18b

{}