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

Este artigo faz parte do Passo 1: rever as diferenças da API na série de listas de verificação de planeamento de migração de aplicações do Azure AD Graph.

Muitas funcionalidades no Microsoft Graph funcionam da mesma forma que os homólogos do Graph do Azure Active Directory (Azure AD). No entanto, alguns foram alterados ou melhorados. Neste artigo, vai aprender a adaptar as suas aplicações para tirar partido destas diferenças.

Este artigo explora a forma como o Microsoft Graph processa:

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

Extensões de diretório

Se a sua aplicação utilizar Azure AD extensões de diretório do Graph, pode continuar a utilizar as mesmas APIs básicas (com os URLs de pedido do Microsoft Graph) para:

• Faça a gestão das definições da extensão de diretório com o recurso extensionProperty e os métodos associados.
• Obtenha as propriedades de extensão disponíveis com a ação getAvailableExtensionProperties .
• Ler valores de extensão com GET e para utilizadores, apenas com uma $select consulta através do v1.0 ponto final
• Procurar valores de extensão com GET e $filter
• Atualizar valores de extensão com PATCH
• Remover valores de extensão com PATCH (definido como nulo)

O Microsoft Graph fornece uma experiência de programador de extensões de esquema melhorada, que atualmente não é retrocompatível com Azure AD extensões de diretório do Graph. Para saber mais, veja Escolher um tipo de extensão para a sua aplicação.

Abordagem de migração recomendada

Se a sua aplicação Azure AD Graph utilizar extensões de diretório, siga uma abordagem incremental para migrar a aplicação para o Microsoft Graph.

Primeiro, mude a sua aplicação para utilizar chamadas do Microsoft API do Graph, mas permita que a aplicação continue a utilizar Azure AD extensões de diretório do Graph.

Em seguida, pode mudar para a utilização de extensões de esquema do Microsoft Graph. Em alguns casos, a mudança não é adequada. Não mude se:

• A aplicação utiliza extensões de diretório criadas através do AD Connect
• A sua aplicação define valores de extensão de diretório que são utilizados em afirmações de tokens por outras aplicações
• A sua aplicação define valores de extensão de diretório que são utilizados em regras de associação dinâmicas

NOTA: a utilização das propriedades da extensão de esquema do Microsoft Graph como afirmações num token com afirmações opcionais ou numa regra de associação dinâmica ainda não é suportada.

Para mudar para o mais recente modelo de extensão de esquema do Microsoft Graph, tem de:

• Defina novas definições de extensão de esquema com o Microsoft Graph.
• Atualize a aplicação para suportar as novas definições de extensão de esquema.
• Migre os dados das propriedades da extensão de diretório do Azure AD Graph para as propriedades da extensão de esquema do Microsoft Graph. A migração automática de dados não é suportada.

Consultas diferenciais

Azure AD Graph e o Microsoft Graph permitem-lhe registar alterações através de consultas. A abordagem de alto nível é semelhante entre as duas APIs, mas a sintaxe é diferente.

Azure AD Graph chama estas consultas diferenciais enquanto o Microsoft Graph as chama de consultas delta.

A tabela seguinte realça as principais semelhanças e diferenças:

Pedido Delta	Azure AD Graph.	Microsoft Graph
Pedido de dados inicial	Utiliza um parâmetro de consulta: GET /groups?deltaLink=	Utiliza uma função: GET /groups/delta
Obter novas alterações	GET /groups?deltaLink={deltaToken}	GET /groups/delta?$deltaToken={deltaToken}
Sincronizar a partir de agora	Utiliza um cabeçalho HTTP personalizado: ocp-aad-dq-include-only-delta-token: true	Utiliza um parâmetro de consulta: GET /groups/delta?$deltaToken=latest
Registar alterações para objetos de diretório	Obtém alterações para vários recursos (utilizador e grupo) na mesma operação: GET /directoryObject?$filter=isof('User') or isof('Group')&deltaLink=	Utiliza consultas separadas com o Microsoft Graph, uma para cada recurso.
Obter alterações de recursos e relações	Todos os pedidos devolvem alterações de recursos e relações, se o recurso tiver relações.	GET /groups/delta?$expand=members
Resposta a indicar itens novos e alterados	Representa as instâncias recém-criadas com a representação padrão. As instâncias atualizadas são representadas pelo respetivo 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 as instâncias recém-criadas com a representação padrão. As instâncias atualizadas são representadas pelo respetivo 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 recursos padrão. Estas anotações utilizam o formato propertyName@delta, por exemplo members@delta , para as alterações de associação de um grupo.
Resposta a indicar itens eliminados	Indica um item eliminado com uma propriedade adicional de aad.isDeleted definido como verdadeiro.	Indica um item eliminado com a @removed anotação. Também pode conter um código de motivo, que indica se o item foi eliminado, mas pode ser restaurado ou eliminado permanentemente.

Se a sua aplicação já estiver a armazenar dados de estado, considere utilizar a funcionalidade "sincronizar a partir de agora" para ajudar a gerir a transição para consultas delta.

Envio em lote

Azure AD Graph utilizou um sistema denominado mensagens MIME multi-partes para gerir a criação de lotes. O Microsoft Graph utiliza a criação de batches JSON para permitir até 20 pedidos numa única operação de lote. O mecanismo de criação de batches JSON é mais simples de utilizar, especialmente em conjunto com as bibliotecas de análise JSON. Também permite a sequenciação de operações em lote. No entanto, não é retrocompatível com a abordagem de criação de batches do Azure AD Graph.

Próxima etapa

Rever a lista de verificação de migração novamente