Compartilhar via


Executar bulkUpload

Namespace: microsoft.graph

Execute um novo carregamento em massa com a tarefa de sincronização. Utilize este ponto final da API para ingerir dados no serviço de sincronização Microsoft Entra. O serviço de sincronização aplica os mapeamentos associados à tarefa de sincronização e processa os dados recebidos. O limite de taxa para esta API é de 40 pedidos por segundo. Cada pedido pode conter um máximo de 50 operações de utilizador na matriz operações de pedido em massa.

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Tipo de permissão Permissões com menos privilégios Permissões com privilégios superiores
Delegado (conta corporativa ou de estudante) SynchronizationData-User.Upload Indisponível.
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application SynchronizationData-User.Upload.OwnedBy SynchronizationData-User.Upload

Observação

Esta API destina-se principalmente a ser utilizada numa aplicação ou serviço responsável por processar dados de identidade autoritativas e carregá-la para Microsoft Entra ID. Os administradores de inquilinos podem configurar um principal de serviço ou uma identidade gerida para conceder permissão para efetuar o carregamento. Não existe uma função de diretório incorporada Microsoft Entra atribuível pelo utilizador separada para esta API. Fora das aplicações que tenham obtido SynchronizationData-User.Upload permissão com o consentimento do administrador, apenas os utilizadores administradores com função de Administrador Global podem invocar a API.

Solicitação HTTP

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

No ponto final da API, {servicePrincipalId} refere-se ao ID do objeto do principal de serviço e {jobId} refere-se ao ID da tarefa de aprovisionamento.

Cabeçalhos de solicitação

Nome Descrição
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type application/scim+json. Obrigatório.

Corpo da solicitação

No corpo do pedido, forneça um tipo de recurso bulkUpload . Veja a secção exemplos de payloads de exemplo.

Resposta

Se for bem-sucedido, devolve uma 202 Accepted resposta e nada no corpo da resposta. Também devolve um cabeçalho Localização para verificar a status do aprovisionamento de pedidos em massa.

Código de Estado HTTP Explicação
202 (Aceite) O pedido em massa é testado para execução e será processado pela tarefa de aprovisionamento associada. A Location chave no cabeçalho de resposta aponta para o ponto final de registos de aprovisionamento que pode ser utilizado para marcar a status do aprovisionamento de pedidos em massa.
400 (Pedido Incorreto) O pedido é inaparável, está sintaticamente incorreto ou viola o esquema. A causa mais comum deste erro é a ausência do cabeçalho do Content-Type pedido. Certifique-se de que está presente e defina como application/scim+json.
401 (Não autorizado) O cabeçalho de autorização é inválido ou está em falta. Certifique-se de que o cabeçalho de autorização tem um token de acesso válido.
403 (Proibido) A operação não é permitida com base no cabeçalho de autorização fornecido. Certifique-se de que o cliente da API tem a SynchronizationData-User.Upload permissão e, para cenários delegados, o autor da chamada tem de ser um administrador global.

Exemplos

Exemplo 1: carregamento em massa com o utilizador SCIM Core e o esquema do Utilizador Empresarial

Solicitação

O seguinte pedido em massa utiliza o esquema Utilizador Principal e Utilizador Empresarial padrão do SCIM. Tem duas operações de utilizador na matriz Operações . Pode enviar um máximo de 50 operações de utilizador em cada pedido em massa.

Detalhes de processamento: O serviço de aprovisionamento lê os dois registos de utilizador. Utiliza o atributo correspondente para userName e externalId que está configurado no mapeamento de atributos da tarefa de aprovisionamento para determinar se pretende criar, atualizar, ativar ou desativar a conta de utilizador no diretório. Resolve a referência do gestor com o manager.value campo . Especifique o externalId gestor do utilizador neste campo. No exemplo seguinte, o serviço de aprovisionamento atribui Barbara Jensen como gestora de 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
}

Resposta

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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

{}

Exemplo 2: carregamento em massa com o espaço de nomes de esquema personalizado SCIM

Solicitação

O seguinte pedido em massa utiliza o esquema Utilizador Principal e Utilizador Empresarial padrão do SCIM. Tem outro espaço de nomes de esquema personalizado chamado urn:contoso:employee com dois atributos HireDate e JobCode. A schemas matriz no objeto de dados é atualizada para incluir o espaço de nomes de esquema personalizado.

Detalhes de processamento: O serviço de aprovisionamento lê os dois registos de utilizador. Utiliza o atributo correspondente para userName e externalId que está configurado no mapeamento de atributos da tarefa de aprovisionamento para determinar se pretende criar, atualizar, ativar ou desativar a conta de utilizador no diretório. Se incluir os dois atributos personalizados e urn:contoso:employee:JobCode no mapeamento de atributos urn:contoso:employee:HireDate da tarefa de aprovisionamento, este é processado e os atributos de destino correspondentes são definidos.

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
}

Resposta

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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

{}

Exemplo 3: Carregamento em massa para atualizar um utilizador existente

Solicitação

O seguinte pedido em massa ilustra como atualizar atributos de um utilizador Microsoft Entra existente, alterar o departamento do utilizador e desativar o início de sessão do utilizador. Este exemplo pressupõe que configurou um mapeamento para os campos externos, departamento e ativo e que tem um utilizador Microsoft Entra existente que tem um atributo que corresponde ao 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
}

Resposta

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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

{}