Выполнение bulkUpload

  • Статья

Пространство имен: microsoft.graph

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

Выполнение новой массовой отправки с помощью задания синхронизации. Используйте эту конечную точку API для приема данных в службу синхронизации Microsoft Entra. Служба синхронизации применяет сопоставления, связанные с заданием синхронизации, и обрабатывает входящие данные. Ограничение скорости для этого API составляет 40 запросов в секунду. Каждый запрос может содержать не более 50 операций пользователя в массиве операций массового запроса.

Примечание.

Этот API доступен в общедоступной предварительной версии и доступен только для приложений подготовки для входящего трафика на основе API.

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения Разрешения с наименьшими привилегиями Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись) SynchronizationData-User.Upload Недоступно.
Делегированные (личная учетная запись Майкрософт) Не поддерживается. Не поддерживается.
Приложение SynchronizationData-User.Upload Недоступно.

Примечание.

Этот API в первую очередь предназначен для использования в приложении или службе, ответственной за обработку достоверных данных удостоверений и их отправку в Microsoft Entra ID. Администраторы клиента могут настроить субъект-службу или управляемое удостоверение , чтобы предоставить разрешение на выполнение отправки. Для этого API не существует отдельных назначаемых пользователем Microsoft Entra встроенной роли каталога. За пределами приложений, которые получили SynchronizationData-User.Upload разрешение с согласия администратора, только пользователи с ролью глобального администратора могут вызывать API.

HTTP-запрос

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

В конечной точке {servicePrincipalId} API ссылается на идентификатор объекта субъекта-службы и {jobId} указывает на идентификатор задания подготовки.

Заголовки запросов

Имя Описание
Авторизация Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
Content-Type application/scim+json. Обязательно.

Текст запроса

В тексте запроса укажите тип ресурса bulkUpload . Примеры полезных данных см. в разделе примеров.

Отклик

В случае успешного 202 Accepted выполнения возвращает ответ и ничего в тексте ответа. Он также возвращает заголовок Location для проверки состояния подготовки массового запроса.

Код состояния HTTP Объяснение
202 (принято) Массовый запрос выполняется поэтапно и обрабатывается связанным заданием подготовки. Ключ Location в заголовке ответа указывает на конечную точку журналов подготовки, которую можно использовать для проверка состояния подготовки массового запроса.
400 (недопустимый запрос) Запрос неразделим, синтаксически неверный или нарушает схему. Наиболее распространенной причиной этой ошибки является отсутствие заголовка Content-Typeзапроса . Убедитесь, что он присутствует и имеет значение application/scim+json.
401 (не авторизовано) Заголовок авторизации недопустим или отсутствует. Убедитесь, что заголовок авторизации содержит допустимый маркер доступа.
403 (запрещено) Отерация не допускается на основе предоставленной авторизации. Убедитесь, что клиент API имеет разрешение SynchronizationData-User.UploadAPI Graph .

Примеры

Пример 1. Массовая отправка с использованием схемы пользователя SCIM Core и корпоративного пользователя

Запрос

В следующем массовом запросе используется стандартная схема SCIM Core User и Enterprise User. В массиве Operations есть две пользовательские операции. В каждом массовом запросе можно отправить не более 50 пользовательских операций.

Сведения об обработке: Служба подготовки считывает две записи пользователей. Он использует соответствующий атрибут для userName и externalId , настроенный в сопоставлении атрибутов задания подготовки, чтобы определить, следует ли создавать, обновлять, включать или отключать учетную запись пользователя в каталоге. Он разрешает ссылку на диспетчер с помощью manager.value поля . externalId Укажите в этом поле имя руководителя пользователя. В следующем примере служба подготовки назначает Барбару Дженсен менеджером Кэти Дженсен.

POST https://graph.microsoft.com/beta/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 Core User и Enterprise User. У него есть другое пользовательское пространство urn:contoso:employee имен схемы с двумя атрибутами HireDate и JobCode. Массив schemas в объекте данных обновляется для включения пользовательского пространства имен схемы.

Сведения об обработке: Служба подготовки считывает две записи пользователей. Он использует соответствующий атрибут для userName и externalId , настроенный в сопоставлении атрибутов задания подготовки, чтобы определить, следует ли создавать, обновлять, включать или отключать учетную запись пользователя в каталоге. Если включить два настраиваемых атрибута и urn:contoso:employee:JobCode в сопоставление атрибутов urn:contoso:employee:HireDate задания подготовки, они обрабатываются, а соответствующие целевые атрибуты задаются.

POST https://graph.microsoft.com/beta/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, и у вас есть пользователь Microsoft Entra, имеющий атрибут, соответствующий externalId.

POST https://graph.microsoft.com/beta/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

{}