Solicitar diferencias entre Azure Active Directory (Azure AD) Graph y Microsoft Graph

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

Microsoft Graph y la API de Graph azure AD son api de REST y cada una admite convenciones de ODATA para parámetros de consulta. Sin embargo, la sintaxis varía entre estas dos API.

Use Graph Explorer para probar estos patrones de solicitud con sus propios datos, ya que es una excelente manera de obtener información sobre las diferencias de solicitud y respuesta.

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 https://graph.cloudapi.de https://graph.microsoft.de
- China   (21Vianet) https://graph.chinacloudapi.cn https://microsoftgraph.chinacloudapi.cn
{tenant_id} Especifique el identificador del inquilino en la solicitud. Es opcional especificar un identificador de inquilino en la solicitud, ya que se deduce del token de acceso.

Si especifica el identificador de inquilino, se encuentra entre la dirección URL de la solicitud y {version} la dirección URL de la {resource} solicitud.
{version} Especifique la versión de lanzamiento de Azure AD Graph en la solicitud mediante un parámetro de consulta obligatorio. Especifique la versión de lanzamiento de Microsoft Graph en la solicitud como parte de la ruta de acceso de dirección URL justo después del extremo de servicio.

Puede seguir usando los mismos parámetros de consulta en Microsoft Graph que Azure AD Graph.

Comparación de solicitudes de ejemplo

Supongamos que desea una lista de todos los usuarios con nombres que empiezan por "Dan".

En Azure AD Graph, puede usar esta solicitud:

GET https://graph.windows.net/contoso.com/users?$filter=startswith(givenName,'Dan')&api-version=1.6 o

GET https://graph.windows.net/myOrganization/users?$filter=startswith(givenName,'Dan')&api-version=1.6

Esta solicitud:

  • Destinos de la versión 1.6 de Azure AD Graph.
  • Especifica como contoso.com el identificador de inquilino. La alternativa muestra el uso de un alias myOrganization basado en el identificador de inquilino en el token de acceso.
  • Llama al recurso users.
  • Usa el $filter parámetro de consulta para limitar la respuesta a nombres determinados que comienzan por Dan .

Los resultados incluyen usuarios con nombres como Daniel, Danforth, Danielle, Danerys, y así sucesivamente.

Una solicitud similar para Microsoft Graph sería:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName,'Dan')

Aquí:

  • La versión es v1.0 .
  • El identificador de inquilino se deduce del token de acceso (no se muestra).
  • El recurso y $filter el parámetro de consulta son los mismos que la consulta de Azure AD.

NOTA: Si usa la biblioteca de cliente de .NET de Azure AD Graph, consulte Bibliotecas de cliente .NET para obtener más estrategias y asistencia específicas para pasar a la biblioteca de cliente de .NET de Microsoft Graph.

Identificadores de clave: objectId vs id

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

Propiedades y propiedades predeterminadas $select

Usa el parámetro de consulta, en solicitudes GET, para personalizar la respuesta para $select incluir todas las propiedades que la aplicación requiere.

Microsoft Graph obtener o enumerar operaciones para recursos de usuario o grupo devuelve solo un subconjunto de todas las propiedades, conocidas como propiedades predeterminadas. Las propiedades predeterminadas representan las propiedades más usadas para un recurso. Por otra parte, Azure AD Graph devuelve el conjunto completo de todas las propiedades del recurso respectivo.

Para obtener otras propiedades en v1.0, la aplicación debe solicitarlas explícitamente mediante el $select parámetro de consulta. Esto incluye cualquier extensión de esquema de directorio que pueda usar la aplicación. Es un procedimiento recomendado solicitar solo las propiedades que realmente necesita la aplicación.

Para ilustrar la diferencia, use Graph Explorer para ejecutar las siguientes solicitudes y comparar las diferentes respuestas.

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

Revise las respuestas de cada consulta. Observará que la versión /beta devuelve la información de direcciones, pero no la versión /v1.0. Esto se debe a que las propiedades de dirección no están en el conjunto de propiedades predeterminado.

Si la aplicación se basa en las propiedades de dirección, debes actualizar las solicitudes de v1.0 para incluir el $select parámetro de consulta:

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

La respuesta para esta solicitud incluiría las propiedades de la dirección. También incluye la propiedad displayName, pero solo porque se especificó mediante el parámetro de consulta.

Para obtener más información sobre:

  • Propiedades predeterminadas en el usuario, vea usuarios
  • El $select parámetro y otros parámetros de consulta ODATA admitidos, vea Use query parameters to customize responses.
  • Esta y otras optimizaciones recomendadas, consulte Procedimientos recomendados.

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 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, y así sucesivamente.

Las solicitudes Graph azure AD se usan $link para indicar relaciones entre recursos. En Microsoft Graph usa la notación ODATA 4.01 $ref en su lugar.

En la tabla siguiente se muestran varios ejemplos:

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

Al migrar las aplicaciones a Microsoft Graph, busque solicitudes que usen para asociar $link recursos; cámbiese estas para usarlas en $ref su lugar.

Siguientes pasos