Executar bulkUpload

Namespace: microsoft.graph

Execute um novo bulkUpload usando o trabalho de sincronização. Use esse ponto de extremidade de API para ingerir dados no serviço de sincronização do Microsoft Entra. O serviço de sincronização aplica os mapeamentos associados ao trabalho de sincronização e processa os dados de entrada. O limite de taxa para essa API é de 40 solicitações por segundo. Cada solicitação pode conter no máximo 50 operações de usuário na matriz Operations de solicitação em massa.

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão Permissões menos privilegiadas Permissões com privilégios mais elevados
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

Essa API destina-se principalmente ao uso em um aplicativo ou serviço responsável por processar dados de identidade autoritativos e carregá-los no Microsoft Entra ID. Os administradores de locatários podem configurar uma entidade de serviço ou uma identidade gerenciada para conceder permissão para executar o upload. Não há nenhuma função de diretório interna do Microsoft Entra atribuível pelo usuário separada para essa API. Fora dos aplicativos que adquiriram SynchronizationData-User.Upload permissão com o consentimento do administrador, os usuários administradores com a função de administrador de usuários podem invocar a API.

Solicitação HTTP

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

No ponto de extremidade da API, {servicePrincipalId} refere-se à ID do objeto da entidade de serviço e {jobId} refere-se à ID do trabalho de provisionamento.

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 da solicitação, forneça um tipo de recurso bulkUpload . Consulte a seção de exemplos para obter conteúdos de exemplo.

Resposta

Se for bem-sucedido, retorna uma 202 Accepted resposta e nada no corpo da resposta. Ele também retorna um cabeçalho Location para verificar o status do provisionamento de solicitação em massa.

Código de status HTTP Explicação
202 (Aceito) A solicitação em massa é preparada para execução e é processada pelo trabalho de provisionamento associado. A Location chave no cabeçalho de resposta aponta para o ponto de extremidade dos logs de provisionamento que pode ser usado para marcar o status do provisionamento de solicitação em massa.
400 (solicitação inválida) A solicitação não pode ser analisada, sintaticamente incorreta ou viola o esquema. A causa mais comum desse erro é a ausência do Content-Type cabeçalho da solicitação. Verifique se ele está presente e definido como application/scim+json.
401 (Não autorizado) O cabeçalho de autorização é inválido ou está ausente. Verifique se 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. Verifique se o cliente da API tem a SynchronizationData-User.Upload permissão e, para cenários delegados, o chamador deve ser um administrador de usuários.

Exemplos

Exemplo 1: Carregamento em massa usando o usuário SCIM Core e o esquema de Usuário Corporativo

Solicitação

A solicitação em massa a seguir usa o esquema padrão SCIM de Usuário Principal e Usuário Corporativo. Ele tem duas operações de usuário na matriz Operações . Você pode enviar no máximo 50 operações de usuário em cada solicitação em massa.

Detalhes de processamento: O serviço de provisionamento lê os dois registros de usuário. Ele usa o atributo correspondente para userName e externalId que é configurado no mapeamento de atributo do trabalho de provisionamento para determinar se é necessário criar, atualizar, habilitar ou desabilitar a conta de usuário no diretório. Ele resolve a referência do gerente usando o manager.value campo. Especifique o externalId gerente do usuário neste campo. No exemplo a seguir, o serviço de provisionamento atribui Barbara Jensen como gerente 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/v1.0/auditLogs/provisioning/?$filter=jobid%20eq%20'API2AAD.b16687d38faf42adb29892cdcaf01c6e.1a03de52-b9c3-4e2c-a1e3-9145aaa8e530'"
request-id: beeb9ea0-f7e4-4fe7-8507-cd834c88f18b

{}

Exemplo 2: Upload em massa usando namespace de esquema personalizado SCIM

Solicitação

A solicitação em massa a seguir usa o esquema padrão SCIM de Usuário Principal e Usuário Corporativo. Ele tem outro namespace de esquema personalizado chamado urn:contoso:employee com dois atributos HireDate e JobCode. A schemas matriz no objeto de dados é atualizada para incluir o namespace de esquema personalizado.

Detalhes de processamento: O serviço de provisionamento lê os dois registros de usuário. Ele usa o atributo correspondente para userName e externalId que é configurado no mapeamento de atributo do trabalho de provisionamento para determinar se é necessário criar, atualizar, habilitar ou desabilitar a conta de usuário no diretório. Se você incluir os dois atributos urn:contoso:employee:HireDate personalizados e urn:contoso:employee:JobCode no mapeamento de atributos do trabalho de provisionamento, ele será processado e os atributos de destino correspondentes serã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/v1.0/auditLogs/provisioning/?$filter=jobid%20eq%20'API2AAD.b16687d38faf42adb29892cdcaf01c6e.1a03de52-b9c3-4e2c-a1e3-9145aaa8e530'"
request-id: beeb9ea0-f7e4-4fe7-8507-cd834c88f18b

{}

Exemplo 3: upload em massa para atualizar um usuário existente

Solicitação

A solicitação em massa a seguir ilustra como atualizar os atributos de um usuário existente do Microsoft Entra, alterar o departamento do usuário e desabilitar a entrada do usuário. Este exemplo pressupõe que você tenha configurado um mapeamento para externalId, departamento e campos ativos e que tenha um usuário existente do Microsoft Entra que tenha um atributo correspondente a 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/v1.0/auditLogs/provisioning/?$filter=jobid%20eq%20'API2AAD.b16687d38faf42adb29892cdcaf01c6e.1a03de52-b9c3-4e2c-a1e3-9145aaa8e530'"
request-id: beec9ea0-f7e4-4fe7-8507-cd834c88f18b

{}
  • Last updated on