Compartir a través de

Diferencias de solicitudes entre Azure AD Graph y Microsoft Graph

  • Artículo

Este artículo forma parte del paso 1: revisar las diferencias de API del proceso para migrar aplicaciones.

Microsoft Graph y el Graph API de Azure Active Directory (Azure AD) son API REST que admiten convenciones de OData para parámetros de consulta. Sin embargo, la sintaxis varía entre estas dos API.

Use el Explorador de Graph para probar estos patrones de solicitud con sus propios datos y obtener información sobre las diferencias de solicitud y respuesta antes de actualizar el código.

Solicitudes básicas

En la tabla siguiente se resaltan las principales diferencias de solicitud entre las dos API:

Detalles de la solicitud Azure AD Graph Microsoft Graph
Sintaxis de solicitud https://graph.windows.net/{tenant_id}/{resource}?{version}&query-parameters https://graph.microsoft.com/{version}/{resource}?query-parameters
Puntos de conexión de servicio:
-Global https://graph.windows.net https://graph.microsoft.com
- US Gov L4 https://graph.microsoftazure.us https://graph.microsoft.us
- US Gov L5 (DOD) https://graph.microsoftazure.us https://dod-graph.microsoft.us
- Alemania (retirado) https://graph.cloudapi.de https://graph.microsoft.de
- China (21Vianet) https://graph.chinacloudapi.cn https://microsoftgraph.chinacloudapi.cn
{tenant_id} Especifique el identificador de inquilino o el nombre de dominio en la solicitud. Opcional. El identificador de inquilino se deduce del token de acceso.

Si especifica el identificador de inquilino, use esta sintaxis: https://graph.microsoft.com/{version}/{tenant_id}/{resource}?query-parameters.
{version} Especifique la versión de versión de Azure AD Graph en la solicitud mediante un parámetro de consulta necesario. Especifique la versión de versión de Microsoft Graph en la solicitud como parte de la ruta de acceso de dirección URL justo después del punto de conexión de servicio.

La sintaxis del parámetro de consulta es la misma para Microsoft Graph y Azure AD Graph. Sin embargo, Microsoft Graph admite más parámetros de consulta y funcionalidades de consulta que Azure AD Graph.

Comparación de solicitudes de ejemplo

Supongamos que quiere una lista de todos los usuarios con nombres que empiecen por "Dan" en el inquilino de Contoso. En la tabla siguiente se muestran las diferencias de solicitud entre Azure AD Graph y Microsoft Graph.

Azure AD Graph Microsoft Graph
GET https://graph.windows.net/contoso.com/users?$filter=startswith(givenName,'Dan')&api-version=1.6 GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName,'Dan')

Identificadores de clave principal: objectId vs id

En Azure AD Graph, todos los tipos de recursos de entidad tienen un identificador único (o clave principal) denominado objectId. Para la mayoría de las entidades (a menos que se indique lo contrario), este identificador se denomina id en Microsoft Graph.

Además de la clave principal, algunas entidades admiten un identificador de clave alternativo. Por ejemplo, los recursos application y servicePrincipal de Microsoft Graph admiten un identificador de clave alternativo para su propiedad appId .

Propiedades predeterminadas y $select

Es un procedimiento recomendado solicitar solo las propiedades que realmente necesita la aplicación. Use el parámetro de $select consulta, en las solicitudes GET, para personalizar la respuesta para incluir solo las propiedades que requiere la aplicación.

En algunos casos en Microsoft Graph, por ejemplo, las operaciones GET o LIST para los recursos de usuario y grupo , solo se devuelve un subconjunto de todas las propiedades. Estas propiedades predeterminadas representan las propiedades más usadas para los recursos. Por otro lado, Azure AD Graph devuelve el conjunto completo de todas las propiedades del recurso correspondiente. Cuando el recurso devuelve solo las propiedades predeterminadas, la aplicación debe solicitar explícitamente otras propiedades mediante el parámetro de $select consulta.

Para ilustrar la diferencia, use el Explorador de Graph para ejecutar las siguientes solicitudes y comparar las distintas respuestas.

GET https://graph.microsoft.com/v1.0/me/
GET https://graph.microsoft.com/beta/me/

Observe la diferencia en las respuestas. La /beta versión devuelve más propiedades que la /v1.0 versión. Si la aplicación se basa en la propiedad streetAddress , por ejemplo, debe actualizar v1.0 las solicitudes para usar el parámetro de $select consulta para solicitar la propiedad streetAddress , además de otras propiedades que necesita la aplicación. Por ejemplo:

https://graph.microsoft.com/v1.0/me?$select=displayName,streetAddress,city,state,postalCode

Para obtener más información sobre:

Relaciones y propiedades de navegación

Las relaciones (o propiedades de navegación) son un concepto clave en Azure AD Graph y Microsoft Graph, creando una red de recursos relacionados. Por ejemplo, las propiedades manager y directReports amplían el recurso de usuario para proporcionar la jerarquía organizativa.

Las relaciones también definen pertenencias, como los grupos a los que pertenece un usuario, los miembros que pertenecen a un grupo o un rol de directorio, etc.

Las solicitudes de Azure AD Graph se usan $links para indicar las relaciones entre los recursos. Microsoft Graph usa la notación OData v4.01 $ref en su lugar.

En la tabla siguiente se muestran varios ejemplos:

Tarea Azure AD Graph Microsoft Graph
Agregar miembro POST /groups/{id}/$links/members POST /groups/{id}/members/$ref
Vínculos de miembros de lista GET /groups/{id}/$links/members GET /groups/{id}/members/$ref
Enumerar miembros GET /groups/{id}/members GET /groups/{id}/members
Quitar miembro DELETE /groups/{id}/$links/members/{id} DELETE /groups/{id}/members/{id}/$ref

Al migrar las aplicaciones a Microsoft Graph, actualice las referencias que usan $links para asociar recursos para usarlos $ref en su lugar.

Paso siguiente

Vuelva a revisar la lista de comprobación de migración.