Diferenças de recursos entre o Azure AD Graph e o Microsoft GraphFeature differences between Azure AD Graph and Microsoft Graph

Este artigo faz parte da etapa 1: revisar as diferenças de API do processo de migração de aplicativos.This article is part of step 1: review API differences of the process to migrate apps.

Muitos recursos do Microsoft Graph funcionam de forma semelhante aos seus colegas do Azure AD Graph.Many features in Microsoft Graph work similarly to their Azure AD Graph counterparts. No entanto, alguns foram alterados e/ou aprimorados.However, a few have been changed and/or improved. Aqui, você aprenderá como adaptar seus aplicativos para aproveitar essas diferenças.Here, you'll learn how to adapt your apps to take advantage of these differences. Frequentemente, as alterações são secundárias, mas vale a pena.Frequently, the changes are minor, but well worth the effort.

Este artigo explora como o Microsoft Graph trata:This article explores how Microsoft Graph handles:

  • Extensões de esquema de diretórioDirectory schema extensions
  • Consultas diferenciaisDifferential queries
  • Envio em loteBatching

Extensões de esquema de diretórioDirectory schema extensions

Se o aplicativo usar extensões de diretório do Azure AD Graph, você poderá continuar usando as mesmas APIs básicas (com as URLs de solicitação do Microsoft Graph) para:If your app uses Azure AD Graph directory extensions, you can continue to use the same basic APIs (with Microsoft Graph request URLs) to:

  • Gerenciar definições de propriedade de extensão usando a propriedade extensionproperties no recurso [Application] [/Graph/API/Resources/Application? View = Graph-REST-v 1.0).Manage extension property definitions using the extensionProperties property on the [application][/graph/api/resources/application?view=graph-rest-v1.0) resource.
  • Obter as propriedades de extensão disponíveis usando a ação getAvailableExtensionProperties .Get available extension properties using the getAvailableExtensionProperties action.
  • Ler valores de extensão usando GET e $selectRead extension values using GET and $select
  • Pesquisar valores de extensão usando GET e $filterSearch on extension values using GET and $filter
  • Atualizar valores de extensão usando PATCHUpdate extension values using PATCH
  • Remover valores de extensão usando PATCH (definido como nulo)Remove extension values using PATCH (set to null)

O Microsoft Graph fornece uma experiência de desenvolvedor aprimorada de extensões de esquema, que atualmente não é compatível com as extensões de diretório do Azure AD Graph.Microsoft Graph provides an enhanced schema extensions developer experience, which today is not backwards compatible with Azure AD Graph directory extensions. Para saber mais, veja extensões de esquema em adicionar dados personalizados.To learn more, see schema extensions in add custom data.

Se seu aplicativo do Azure AD Graph usa extensões de diretório, faça uma abordagem incremental para migrar o aplicativo para o Microsoft Graph.If your Azure AD Graph app uses directory extensions, take an incremental approach to migrate the app to Microsoft Graph.

Primeiro, alterne seu aplicativo para usar chamadas da API do Microsoft Graph, mas deixe que o aplicativo continue a aproveitar as extensões de diretório do Azure AD Graph.First, switch your app to using Microsoft Graph API calls, but let the app continue to leverage Azure AD Graph directory extensions.

Em seguida, você pode alternar para usar extensões de esquema do Microsoft Graph.Then, you can switch to using Microsoft Graph schema extensions. Em alguns casos, a alternância não será apropriada.In some cases, switching will not be appropriate. Não alternar se:Do not switch if:

  • Seu aplicativo usa extensões de diretório criadas por meio do AD ConnectYour app uses directory extensions created through AD Connect
  • Seu aplicativo define valores de extensão de diretório que são usados em declarações de token por outros aplicativosYour app sets directory extension values that are used in token claims by other apps
  • Seu aplicativo define valores de extensão de diretório que são usados em regras de associação dinâmicasYour app sets directory extension values that are used in dynamic membership rules

Observação: o uso de propriedades de extensão de esquema do Microsoft Graph como declarações em um token que usa declarações opcionais ou em uma regra de associação dinâmica ainda não tem suporte.NOTE: Using Microsoft Graph schema extension properties as claims in a token using optional claims or in a dynamic membership rule is not yet supported.

Para alternar para o modelo de extensão de esquema do Microsoft Graph mais recente, você precisará:To switch to the newer Microsoft Graph schema extension model, you'll need to:

  • Definir novas definições de extensão de esquema usando o Microsoft Graph.Define new schema extension definitions using Microsoft Graph.
  • Atualize o aplicativo para dar suporte às novas definições de extensão de esquema.Update the app to support the new schema extension definitions.
  • Migre os dados das propriedades de extensão de esquema do Azure AD para as novas propriedades de extensão de esquema do Microsoft Graph.Migrate the data from the Azure AD schema extension properties to the new Microsoft Graph schema extension properties. Não há suporte para a migração automática de dados.Automatic migration of data is not supported.

Consultas diferenciaisDifferential queries

O Azure AD Graph e o Microsoft Graph permitem que você controle alterações usando consultas.Azure AD Graph and Microsoft Graph let you track changes using queries. A abordagem de alto nível é semelhante entre as duas APIs, mas a sintaxe é diferente.The high-level approach is similar between the two APIs, but the syntax is different.

O Azure AD Graph chama essas consultas diferenciais.Azure AD Graph calls these differential queries. No Microsoft Graph, eles são consultas Delta.In Microsoft Graph, they're delta queries.

A tabela a seguir destaca as principais semelhanças e diferenças:The following table highlights key similarities and differences:

Solicitação DeltaDelta request Azure AD Graph.Azure AD Graph Microsoft GraphMicrosoft Graph
Solicitação de dados inicialInitial data request Usa um parâmetro de consulta:Uses a query parameter:
GET /groups?deltaLink=
O usa uma função:Uses a function:
GET /groups/delta
Obter novas alteraçõesGet new changes GET /groups?deltaLink={deltaToken} GET /groups/delta?$deltaToken={deltaToken}
Sincronizar a partir de agoraSync from now Usa um cabeçalho HTTP personalizado:Uses a custom HTTP header:
ocp-aad-dq-include-only-delta-token: true
Usa um parâmetro de consulta:Uses a query parameter:
GET /groups/delta?$deltaToken=latest
Controlar alterações para o directoryObjectsTrack changes for directoryObjects Obtém alterações para vários recursos (usuário e grupo) na mesma operação:  Gets changes for multiple resource (user and group) in the same operation:  
GET /directoryObject?$filter=isof('User') or isof('Group')&deltaLink=
Usa consultas separadas com o Microsoft Graph, uma para cada recurso.Uses separate queries with Microsoft Graph, one for each resource.
Obter alterações de recursos e relaçõesGet resource and relationship changes Todas as solicitações retornam as alterações de recurso e relação, se o recurso tiver relações.All requests return resource and relationship changes, if the resource has relationships. GET /groups/delta?$expand=members
Resposta que indica itens novos e alteradosResponse indicating new and changed items
  • Representa instâncias recém-criadas usando sua representação padrão.Represents newly created instances using their standard representation.

  • As instâncias atualizadas são representadas por sua ID com pelo menos as propriedades que foram atualizadas.Updated instances are represented by their id with at least the properties that have been updated. Outras propriedades podem ser incluídas.Other properties may be included.

  • As relações são representadas como o directoryLinkChange tipo.Relationships are represented as the directoryLinkChange type.

  • Representa instâncias recém-criadas usando sua representação padrão.Represents newly created instances using their standard representation.

  • As instâncias atualizadas são representadas por sua ID com pelo menos as propriedades que foram atualizadas.Updated instances are represented by their id with at least the properties that have been updated. Outras propriedades podem ser incluídas.Other properties may be included.

  • As relações são representadas como anotações na representação de recursos padrão.Relationships are represented as annotations on the standard resource representation. Essas anotações usam o formato propertyName@delta , por exemplo, members@delta para as alterações de associação de um grupo.These annotations use the format propertyName@delta, for example members@delta for a group's membership changes.

Resposta indicando itens excluídosResponse indicating deleted items Indica um item excluído com uma propriedade adicional de AAD. IsDeleted definida como true.Indicates a deleted item with an additional property of aad.isDeleted set to true. Indica um item excluído com a @ anotação removida.Indicates a deleted item with the @removed annotation. Ele 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.It may also contain a reason code, which indicates if the item is deleted, but can be restored, or is permanently deleted.

Se seu aplicativo já estiver armazenando dados de estado, considere o uso de "sincronizar a partir de agora" mostrado anteriormente para ajudar a gerenciar a transição para consultas Delta.If your app is already storing state data, consider using the "sync from now" shown earlier to help manage the transition to delta queries.

Envio em loteBatching

O Azure AD Graph usava um sistema chamado mensagens MIME de várias partes para gerenciar o envio em lote.Azure AD Graph used a system called multi-part MIME messages to manage batching. O Microsoft Graph usa o processamento em lotes JSON para permitir até 20 solicitações em uma única operação em lote.Microsoft Graph uses JSON batching to permit up to 20 requests in a single batch operation. O mecanismo de lote JSON é muito mais simples de usar, especialmente em conjunto com as bibliotecas de análise JSON.The JSON batching mechanism is significantly simpler to use, especially together with JSON parsing libraries. Também permite operações em lote de sequenciamento.It also allows for sequencing batch operations. No entanto, não é compatível com versões anteriores da abordagem de lotes do Azure AD Graph.However, it is not backwards compatible with the Azure AD Graph batching approach.

Próximas etapasNext Steps