Diferenças de recursos entre o Azure AD Graph e o Microsoft Graph

Este artigo faz parte da Etapa 1: examinar as diferenças de API na série de lista de verificação de planejamento de migração do aplicativo Graph do Azure AD.

Muitos recursos do Microsoft Graph funcionam de maneira semelhante aos equivalentes do Graph do Azure Active Directory (Azure AD). No entanto, alguns mudaram ou melhoraram. Este artigo explica como adaptar seus aplicativos para aproveitar essas diferenças.

Este artigo explora como o Microsoft Graph lida:

  • Extensões de esquema de diretório
  • Consultas diferenciais
  • Envio em lote

Extensões de diretório

Se o aplicativo usar extensões de diretório do Graph do Azure AD, continue usando as mesmas APIs básicas (com URLs de solicitação do Microsoft Graph) para:

  • Gerencie definições de extensão de diretório usando o recurso extensionProperty e métodos associados.
  • Obtenha as propriedades de extensão disponíveis usando a ação getAvailableExtensionProperties .
  • Ler valores de extensão usando GET e para usuários, somente com uma $select consulta por meio do v1.0 ponto de extremidade
  • Pesquisar valores de extensão usando GET e $filter
  • Atualizar valores de extensão usando PATCH
  • Remova valores de extensão usando PATCH (definido como nulo)

O Microsoft Graph fornece uma experiência de desenvolvedor de extensões de esquema aprimorada, que não é compatível com as extensões de diretório do Azure AD Graph. Para saber mais, consulte Escolher um tipo de extensão para seu aplicativo.

Se o aplicativo do Azure AD Graph usa extensões de diretório, adote uma abordagem incremental para migrar o aplicativo para o Microsoft Graph.

Primeiro, alterne seu aplicativo para usar chamadas de API do Graph Microsoft, mas deixe o aplicativo continuar a usar as extensões de diretório do Azure AD Graph.

Em seguida, alterne para o uso de extensões de esquema do Microsoft Graph. Em alguns casos, a troca não é apropriada. Não alterne se:

  • Seu aplicativo usa extensões de diretório criadas por meio do AD Connect
  • Seu aplicativo define valores de extensão de diretório que são usados em declarações de token por outros aplicativos
  • Seu aplicativo define valores de extensão de diretório que são usados em regras de associação dinâmica

OBSERVAÇÃO: o uso de propriedades de extensão de esquema do Microsoft Graph como declarações em um token usando declarações opcionais ou em uma regra de associação dinâmica ainda não é compatível.

Para alternar para o novo modelo de extensão de esquema do Microsoft Graph, você precisa:

  • Defina novas definições de extensão de esquema usando o Microsoft Graph.
  • Atualize o aplicativo para dar suporte às novas definições de extensão de esquema.
  • Migre os dados das propriedades de extensão do diretório do Azure AD Graph para as propriedades de extensão de esquema do Microsoft Graph. Não há suporte para a migração automática de dados.

Consultas diferenciais

O Azure AD Graph e o Microsoft Graph permitem acompanhar as alterações usando consultas. A abordagem de alto nível é semelhante entre as duas APIs, mas a sintaxe é diferente.

O Azure AD Graph chama essas consultas diferenciais, enquanto o Microsoft Graph as chama de consultas delta.

A tabela a seguir destaca as principais semelhanças e diferenças:

Solicitação delta Azure AD Graph. Microsoft Graph
Solicitação inicial de dados Usa um parâmetro de consulta:
GET /groups?deltaLink=		 Usa uma função:
GET /groups/delta
Obter novas alterações GET /groups?deltaLink={deltaToken} GET /groups/delta?$deltaToken={deltaToken}
Sincronizar a partir de agora Usa um cabeçalho HTTP personalizado:
ocp-aad-dq-include-only-delta-token: true		 Usa um parâmetro de consulta:
GET /groups/delta?$deltaToken=latest
Controlar alterações para objetos de diretório Obtém alterações para vários recursos (usuário e grupo) na mesma operação:
GET /directoryObject?$filter=isof('User') or isof('Group')&deltaLink=		 Usa consultas separadas com o Microsoft Graph, uma para cada recurso.
Obter alterações de recursos e relacionamentos Todas as solicitações retornam alterações de recurso e de relacionamento, se o recurso tiver relacionamentos. GET /groups/delta?$expand=members
Resposta indicando itens novos e alterados

  • Representa instâncias recém-criadas usando sua representação padrão.

  • As instâncias atualizadas são representadas por sua id com pelo menos as propriedades que foram atualizadas. Outras propriedades podem ser incluídas.

  • As relações são representadas como o directoryLinkChange tipo.

  • Representa instâncias recém-criadas usando sua representação padrão.

  • As instâncias atualizadas são representadas por sua id com pelo menos as propriedades que foram atualizadas. Outras propriedades podem ser incluídas.

  • As relações são representadas como anotações na representação de recurso padrão. Essas anotações usam o formato propertyName@delta, por exemplo members@delta , para alterações de associação de um grupo.
Resposta indicando itens excluídos Indica um item excluído com uma propriedade adicional de aad.isDeleted definida como true. Indica um item excluído com a @removed anotação. Também pode conter um código de motivo, que indica se o item foi excluído, mas pode ser restaurado ou excluído permanentemente.

Se o aplicativo já armazena dados de estado, use a funcionalidade "sincronizar a partir de agora" para ajudar a gerenciar a transição para consultas delta para recursos com suporte.

Envio em lote

O Azure AD Graph usava um sistema chamado mensagens MIME de várias partes para gerenciar o envio em lote. O Microsoft Graph usa o envio em lote JSON para permitir até 20 solicitações em uma única operação de lote. O mecanismo de envio em lote JSON é mais simples de usar, especialmente com bibliotecas de análise JSON. Ele também permite o sequenciamento de operações em lote. No entanto, ele não é compatível com versões anteriores da abordagem de envio em lote do Graph do Azure AD.

Próxima etapa

Examine a lista de verificação de migração novamente para garantir que você cobriu todas as etapas necessárias para uma migração tranquila.

  • Last updated on