Executar bulkUpload
Namespace: microsoft.graph
Execute um novo upload em massa usando o trabalho de sincronização. Use esse ponto de extremidade de API para ingerir dados no serviço de sincronização 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 operações de solicitação em massa.
Permissões
Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas 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 privilegiadas mais altas |
|---|---|---|
| Delegado (conta corporativa ou de estudante) | SincronizaçãoData-User.Upload | Indisponível. |
| Delegado (conta pessoal da Microsoft) | Sem suporte. | Sem suporte. |
| Application | SincronizaçãoData-User.Upload | Indisponível. |
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 em Microsoft Entra ID. Os administradores do locatário 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 Microsoft Entra atribuível ao usuário separada para essa API. Fora dos aplicativos que adquiriram SynchronizationData-User.Upload permissão com o consentimento do administrador, somente usuários administradores com função de Administrador Global 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 exemplos para conteúdos de exemplo.
Resposta
Se for bem-sucedido, retornará uma 202 Accepted resposta e nada no corpo da resposta. Ele também retorna um cabeçalho Local 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 é realizada para execução e será processada pelo trabalho de provisionamento associado. A Location chave no cabeçalho de resposta aponta para o ponto de extremidade de logs de provisionamento que pode ser usado para marcar o status do provisionamento de solicitação em massa. |
| 400 (solicitação incorreta) | A solicitação é indissociável, sintáticamente incorreta ou viola o esquema. A causa mais comum desse erro é a ausência do cabeçalho de solicitação Content-Type . Verifique se ele está presente e definido como application/scim+json. |
| 401 (não autorizado) | O cabeçalho de autorização é inválido ou 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 global. |
Exemplos
- Exemplo 1: carregar em massa usando o usuário do SCIM Core e o esquema de usuário corporativo
- Exemplo 2: upload em massa usando o namespace de esquema personalizado scim
- Exemplo 3: upload em massa para atualizar um usuário existente
Exemplo 1: carregar em massa usando o usuário do SCIM Core e o esquema de usuário corporativo
Solicitação
A solicitação em massa a seguir usa o esquema scim standard User and Enterprise User. Ele tem duas operações de usuário na matriz Operações . Você pode enviar um máximo de 50 operações de usuário em cada solicitação em massa.
Detalhes do processamento: O serviço de provisionamento lê os dois registros de usuário. Ele usa o atributo correspondente para userName e externalId que está configurado no mapeamento de atributo do trabalho de provisionamento para determinar se deve criar, atualizar, habilitar ou desabilitar a conta de usuário no diretório. Ele resolve a referência do gerenciador usando o manager.value campo. Especifique o externalId do gerenciador 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/beta/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 o namespace de esquema personalizado scim
Solicitação
A solicitação em massa a seguir usa o esquema scim standard User and Enterprise User. 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 do processamento: O serviço de provisionamento lê os dois registros de usuário. Ele usa o atributo correspondente para userName e externalId que está configurado no mapeamento de atributo do trabalho de provisionamento para determinar se deve criar, atualizar, habilitar ou desabilitar a conta de usuário no diretório. Se você incluir os dois atributos personalizados urn:contoso:employee:HireDate e urn:contoso:employee:JobCode no mapeamento do atributo de 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/beta/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 atributos de um usuário Microsoft Entra existente, alterar o departamento do usuário e desabilitar a entrada do usuário. Este exemplo pressupõe que você tenha configurado um mapeamento para os campos externalId, department e active, e você tem um usuário 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
{}