visão geral da API de sincronização Microsoft Entra

  • Artigo

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

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:

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, 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 diretório Microsoft Entra:

  • Administrador de Aplicativos
  • Administrador de Aplicativos de Nuvem
  • Administrador de identidade híbrida
  • Administrador Global

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/beta/servicePrincipals?$select=id,appId,displayName&$filter=startswith(displayName, 'salesforce')

Response

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/beta/servicePrincipals?$select=id,appId,displayName&$filter=AppId eq '219561ee-1480-4c67-9aa6-63d861fae3ef'

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/beta/servicePrincipals/{id}/synchronization/jobs
GET https://graph.microsoft.com/beta/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/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}

GET https://graph.microsoft.com/beta/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/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/schema

Response

HTTP/1.1 200 OK

{
    "directories": [],
    "synchronizationRules": []
}

Conteúdo relacionado