visão geral da API de sincronização Microsoft Entra ID
Namespace: microsoft.graph
Microsoft Entra sincronização de identidade (também chamada de "provisionamento") permite automatizar o provisionamento (criação, manutenção) e o des provisionamento (remoção) de identidades de qualquer um dos seguintes:
- Active Directory para Microsoft Entra ID
- Dia de trabalho para Microsoft Entra ID
- Microsoft Entra ID para aplicativos de nuvem, como Dropbox, Salesforce, ServiceNow e muito mais
Você pode usar as APIs de sincronização no Microsoft Graph para gerenciar a sincronização de identidade programaticamente, incluindo:
- Criar, iniciar e interromper trabalhos de sincronização
- Fazer alterações no esquema de sincronização para trabalhos
- Status de sincronização atual.
Para obter mais informações sobre a sincronização no Microsoft Entra ID, confira:
- Automatizar o provisionamento e a desprovisionamento de usuários em aplicativos SaaS com Microsoft Entra ID
- Gerenciar o provisionamento de conta de usuário para aplicativos empresariais no centro de administração do Microsoft Entra
Você também pode experimentar a API no graph Explorer em um locatário de exemplo ou seu próprio locatário.
Trabalho de sincronização
Os trabalhos de sincronização executam a sincronização executando periodicamente em segundo plano, sondando as alterações em um diretório e empurrando-as para outro diretório. O trabalho de sincronização é sempre específico para uma instância específica de um aplicativo em seu locatário. Como parte da configuração do trabalho de sincronização, você precisa dar autorização para ler e gravar objetos no diretório de destino e personalizar o esquema de sincronização do trabalho.
Para obter mais informações, confira trabalho de sincronização.
Esquema de sincronização
O esquema de sincronização define quais objetos serão sincronizados e como eles serão sincronizados. O esquema de sincronização contém a maioria das informações de configuração para um trabalho de sincronização específico. Normalmente, você personalizará alguns dos mapeamentos de atributo ou adicionará um filtro de escopo para sincronizar apenas objetos que satisfaçam uma determinada condição.
O esquema de sincronização inclui os seguintes componentes:
- Definições de diretório
- Regras de sincronização
- Mapeamentos de objetos
Para obter mais informações, confira esquema de sincronização.
Modelo de sincronização
O modelo de sincronização fornece configurações de sincronização pré-configuradas para um determinado aplicativo. Essas configurações (mais importante, esquema de sincronização) serão usadas por padrão para qualquer trabalho de sincronização com base no modelo. Os modelos são especificados pelo desenvolvedor do aplicativo.
Para obter mais informações, confira modelo de sincronização.
Trabalhando com a API de sincronização
Trabalhar com a API de sincronização envolve principalmente o acesso aos recursos synchronizationJob e synchronizationSchema . Para encontrar o recurso synchronizationJob , você precisa saber a ID do objeto da entidade de serviço ao qual o trabalho de sincronização pertence. Os exemplos a seguir mostram como trabalhar com os recursos synchronizationJob e synchronizationSchema .
Authorization
Para trabalhar com as APIs de sincronização Microsoft Entra ID, o Microsoft Graph dá suporte às seguintes permissões granulares:
- Sincronização.Leitura.Tudo
- Synchronization.ReadWrite.All
- Application.ReadWrite.OwnedBy
- Application.Read.All
- Application.ReadWrite.All
E as seguintes funções de Microsoft Entra menos privilegiadas:
- Administrador de Aplicativos
- Administrador de Aplicativos de Nuvem
- Administrador de identidade híbrida
Para obter mais informações sobre os privilégios necessários para chamar cada API, visite a respectiva documentação de referência da API.
Localizar o objeto da entidade de serviço por nome de exibição
O exemplo a seguir mostra como encontrar o objeto da entidade de serviço pelo nome de exibição.
Solicitação
GET https://graph.microsoft.com/v1.0/servicePrincipals?$select=id,appId,displayName&$filter=startswith(displayName, 'salesforce')
Resposta
HTTP/1.1 200 OK
{
"value":[
{
"id":"bc0dc311-87df-48ac-91b1-259bd2c3a31c",
"appId":"f7808c5e-cb57-4e37-8094-406d302c0f8d",
"displayName":"Salesforce"
},
{
"id":"d813d7d7-0f41-4edc-b284-d0dfaf399d15",
"appId":"219561ee-1480-4c67-9aa6-63d861fae3ef",
"displayName":"salesforce 3"
}
]
}
Localizar o objeto da entidade de serviço por ID do aplicativo
O exemplo a seguir mostra como encontrar o objeto da entidade de serviço por ID do aplicativo.
Solicitação
GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='219561ee-1480-4c67-9aa6-63d861fae3ef')?$select=id,appId,displayName
Response
HTTP/1.1 200 OK
{
"value": [
{
"id": "d813d7d7-0f41-4edc-b284-d0dfaf399d15",
"appId": "219561ee-1480-4c67-9aa6-63d861fae3ef",
"displayName": "salesforce 3"
}
]
}
Listar trabalhos de sincronização existentes
O exemplo a seguir mostra como listar trabalhos de sincronização existentes.
Solicitação
GET https://graph.microsoft.com/v1.0/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs
Response
HTTP/1.1 200 OK
{
"value": [
{
"id": "SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa",
"templateId": "SfSandboxOutDelta",
"schedule": {
"expiration": null,
"interval": "PT20M",
"state": "Active"
},
"status": {}
}
]
}
Obter status de trabalho de sincronização
O exemplo a seguir mostra como obter o status de um trabalho de sincronização.
Solicitação
GET https://graph.microsoft.com/v1.0/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs/SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa
Response
HTTP/1.1 200 OK
{
"id": "SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa",
"templateId": "SfSandboxOutDelta",
"schedule": {
"expiration": null,
"interval": "PT20M",
"state": "Active"
},
"status": {}
}
Obter esquema de sincronização
O exemplo a seguir mostra como obter o esquema de sincronização.
Solicitação
GET https://graph.microsoft.com/v1.0/servicePrincipals/{id}/synchronization/jobs/{jobId}/schema
Response
HTTP/1.1 200 OK
{
"directories": [],
"synchronizationRules": []
}