bulkUpload を実行する
名前空間: microsoft.graph
同期ジョブを使用して新しい一括アップロードを実行します。 この API エンドポイントを使用して、Microsoft Entra同期サービスにデータを取り込みます。 同期サービスは、同期ジョブに関連付けられているマッピングを適用し、受信データを処理します。 この API のレート制限は、1 秒あたり 40 要求です。 各要求には、一括要求 Operations 配列に最大 50 個のユーザー 操作 を含めることができます。
アクセス許可
この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「 アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、 アクセス許可のリファレンスを参照してください。
アクセス許可の種類 | 最小特権アクセス許可 | 特権の高いアクセス許可 |
---|---|---|
委任 (職場または学校のアカウント) | SynchronizationData-User.Upload | 注意事項なし。 |
委任 (個人用 Microsoft アカウント) | サポートされていません。 | サポートされていません。 |
アプリケーション | SynchronizationData-User.Upload | 注意事項なし。 |
注:
この API は、主に、権限のある ID データを処理し、それをMicrosoft Entra IDにアップロードするアプリケーションまたはサービス内で使用することを目的とします。 テナント管理者は、アップロードを実行するアクセス許可を付与するように サービス プリンシパルまたはマネージド 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 Core ユーザーとエンタープライズ ユーザー スキーマを使用した一括アップロード
- 例 2: SCIM カスタム スキーマ名前空間を使用した一括アップロード
- 例 3: 既存のユーザーを更新するための一括アップロード
例 1: SCIM Core ユーザーとエンタープライズ ユーザー スキーマを使用した一括アップロード
要求
次の一括要求では、SCIM 標準コア ユーザー スキーマとエンタープライズ ユーザー スキーマが使用されます。 Operations 配列には 2 つのユーザー操作があります。 一括要求ごとに最大 50 個のユーザー操作を送信できます。
処理の詳細: プロビジョニング サービスは、2 つのユーザー レコードを読み取ります。 プロビジョニング ジョブの属性マッピングで構成されている と externalId
に一致する属性userName
を使用して、ディレクトリ内のユーザー アカウントを作成、更新、有効、または無効にするかどうかを決定します。 フィールドを使用してマネージャー参照を manager.value
解決します。 このフィールドに externalId
ユーザーのマネージャーの を指定します。 次の例では、プロビジョニング サービスによって、Kathy Jensen のマネージャーとして Barbara 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 標準コア ユーザー スキーマとエンタープライズ ユーザー スキーマが使用されます。 これには、2 つの属性と JobCode
と を使用して呼び出されたurn:contoso:employee
別のカスタム スキーマ名前空間がありますHireDate
。
schemas
データ オブジェクト内の配列が、カスタム スキーマ名前空間を含むように更新されます。
処理の詳細: プロビジョニング サービスは、2 つのユーザー レコードを読み取ります。 プロビジョニング ジョブの属性マッピングで構成されている と externalId
に一致する属性userName
を使用して、ディレクトリ内のユーザー アカウントを作成、更新、有効、または無効にするかどうかを決定します。 2 つのカスタム属性 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、department、および active フィールドのマッピングを構成しており、externalId と一致する属性を持つ既存のMicrosoft Entra ユーザーがあることを前提としています。
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
{}