Solicitar diferencias entre el gráfico de Azure AD y Microsoft GraphRequest differences between Azure AD Graph and Microsoft Graph

Este artículo forma parte del paso 1: revisión de las diferencias de API del proceso para migrar aplicaciones.This article is part of step 1: review API differences of the process to migrate apps.

Microsoft Graph y la API de Azure AD Graph son API de REST y cada una de ellas admite convenciones de ODATA para los parámetros de consulta.Microsoft Graph and the Azure AD Graph API are both REST APIs and they each support ODATA conventions for query parameters. Sin embargo, la sintaxis varía entre estas dos API.However, the syntax varies between these two APIs.

Use el probador de Graph para probar estos patrones de solicitudes con sus propios datos, ya que es una buena forma de obtener información sobre las diferencias de solicitud y respuesta.Use the Graph Explorer to try these request patterns against your own data, as it's a great way to learn about the request and response differences.

Solicitudes básicasBasic requests

En la tabla siguiente se resaltan las principales diferencias de solicitud entre las dos API:The following table highlights the main request differences between the two APIs:

Detalles de la solicitudRequest details Azure AD GraphAzure AD Graph Microsoft GraphMicrosoft Graph
Sintaxis de solicitudRequest syntax https://graph.windows.net/{tenant_id}/
{resource}?{version}&query-parameters
https://graph.microsoft.com/
{version}/{resource}?query-parameters
Extremos de servicio   :Service endpoints:
- Globales- Global https://graph.windows.net https://graph.microsoft.com
- El   gov L4 de Estados Unidos  - US Gov L4 https://graph.microsoftazure.us https://graph.microsoft.us
-  Gov   L5   (DOD)- US Gov L5 (DOD) https://graph.microsoftazure.us https://dod-graph.microsoft.us
- Alemania- Germany https://graph.cloudapi.de https://graph.microsoft.de
- China   (21Vianet)- China (21Vianet) https://graph.chinacloudapi.cn https://microsoftgraph.chinacloudapi.cn
{tenant_id}{tenant_id} Especifique el identificador del inquilino en la solicitud.Specify the ID of the tenant in the request. Es opcional especificar un identificador de inquilino en la solicitud a medida que se infiere del token de acceso.It's optional to specify a tenant ID in the request as it is inferred from the access token.

Si especifica el identificador de inquilino, se coloca entre el {version} y el {resource} en la dirección URL de la solicitud.If you specify the tenant ID, it goes between the {version} and the {resource} in the request URL.
versi{version} Especifique la versión de lanzamiento de Azure AD Graph en la solicitud con un parámetro de consulta necesario.Specify the release version of Azure AD Graph in the request using a required query parameter. Especifique la versión de lanzamiento de Microsoft Graph en la solicitud como parte de la ruta de acceso de la dirección URL justo después del punto de conexión de servicio.Specify the release version of Microsoft Graph in the request as part of the URL path just after the service endpoint.

Puede seguir usando los mismos parámetros de consulta en Microsoft Graph como Azure AD Graph.You can continue to use the same query parameters in Microsoft Graph as Azure AD Graph.

Ejemplo de comparación de solicitudesExample request comparison

Supongamos que desea una lista de todos los usuarios cuyo nombre empieza por "dan".Suppose you want a list of all users with names beginning with "Dan".

En el gráfico de Azure AD, puede usar esta solicitud:In Azure AD Graph, you might use this request:

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

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

Esta solicitud:This request:

  • Apunta a la versión 1,6 del gráfico de Azure AD.Targets version 1.6 of Azure AD Graph.
  • Especifica contoso.com como el identificador de inquilino.Specifies contoso.com as the tenant ID. La alternativa muestra el uso de un alias myOrganization basándose en el identificador de inquilino en el token de acceso.The alternative shows the use of an alias myOrganization based on the tenant ID in the access token.
  • Llama al recurso users.Calls the users resource.
  • Usa el $filter parámetro de consulta para limitar la respuesta a los nombres especificados que comienzan con Dan .Uses the $filter query parameter to limit the response to given names that begin with Dan.

Entre los resultados se incluyen los usuarios con nombres como Daniel, Danforth, Danielle, Danerys, etc.Results include users with names like Daniel, Danforth, Danielle, Danerys, and so on.

Una solicitud similar para Microsoft Graph sería:A similar request for Microsoft Graph would be:

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

AhoraHere:

  • La versión es v1.0 .The version is v1.0.
  • El identificador de inquilino se deduce del token de acceso (no se muestra).The tenant ID is inferred from the access token (not shown).
  • El parámetro de $filter consulta y recurso es el mismo que la consulta de Azure ad.The resource and $filter query parameter are the same as the Azure AD query.

Nota: Si usa la biblioteca de cliente .net de Azure ad Graph, consulte bibliotecas de cliente .net para obtener estrategias más específicas y ayuda para cambiar a la biblioteca cliente de Microsoft Graph .net.NOTE: If you're using the Azure AD Graph .NET client library, see .NET client libraries for more specific strategies and assistance to move to the Microsoft Graph .NET client library.

Identificadores de clave: objectId vs IDKey identifiers: objectId vs id

En el gráfico de Azure AD, todos los tipos de recursos de entidad tienen un identificador único (o clave) denominado objectId.In Azure AD Graph, all entity resource types have a unique identifier (or key) called objectId. La mayoría de las partes (a menos que se indique lo contrario) este mismo identificador se denomina identificador en Microsoft Graph.For the most part (unless otherwise stated) this same identifier is called id in Microsoft Graph.

Propiedades predeterminadas y $selectDefault properties and $select

Use el $select parámetro de consulta, en las solicitudes GET, para personalizar la respuesta para incluir todas las propiedades que necesita la aplicación.Use the $select query parameter, in GET requests, to customize the response to include all the properties that your app requires.

Las operaciones de obtención o lista de Microsoft Graph para recursos de usuario o grupo solo devuelven un subconjunto de todas las propiedades, conocidas como las propiedades predeterminadas.Microsoft Graph get or list operations for user or group resources returns only a subset of all properties, known as the default properties. Las propiedades predeterminadas representan las propiedades que se usan con más frecuencia para un recurso.The default properties represent the most commonly-used properties for a resource. Por otra parte, Azure AD Graph devuelve el conjunto completo de todas las propiedades del recurso respectivo.On the other hand, Azure AD Graph returns the full set of all properties for the respective resource.

Para obtener otras propiedades en v 1.0, la aplicación debe solicitarlas explícitamente mediante el $select parámetro de consulta.To get other properties in v1.0, your app needs to explicitly request them, using the $select query parameter. Esto incluye las extensiones del esquema de directorio que puede que use la aplicación.This includes any directory schema extensions your app might be using. La práctica recomendada es solicitar solo las propiedades que la aplicación realmente necesita.It's a best practice to only request the properties your app really needs.

Para ilustrar la diferencia, use el probador de Graph para ejecutar las siguientes solicitudes y comparar las distintas respuestas.To illustrate the difference, use Graph Explorer to run the following requests and compare the different responses.

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

Revise las respuestas de cada consulta.Review the responses from each query. Observará que la información de la dirección es devuelta por la versión/beta, pero no por la versión/v1.0.You'll notice that address information is returned by the /beta version, but not the /v1.0 version. Esto se debe a que las propiedades de la dirección no están en el conjunto de propiedades predeterminado.That's because the address properties aren't in the default property set.

Si la aplicación depende de las propiedades de la dirección, debe actualizar las solicitudes v 1.0 para incluir el $select parámetro de consulta:If your app relies on the address properties, you need to update your v1.0 requests to include the $select query parameter:

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

La respuesta a esta solicitud incluiría las propiedades de la dirección.The response for this request would include the address properties. También incluye la propiedad displayName , pero solo porque la especificó el parámetro de consulta.It also includes the displayName property, but only because it was specified by the query parameter.

Para obtener más información sobre:To learn more about:

Relaciones y propiedades de navegaciónRelationships and navigation properties

Las relaciones (o propiedades de navegación) son un concepto clave en Azure AD Graph y Microsoft Graph, creando una red de recursos relacionados.Relationships (or navigation properties) are a key concept in Azure AD Graph and Microsoft Graph, creating a network of related resources. Por ejemplo, las propiedades Manager y directReports amplían el recurso User para proporcionar una jerarquía organizativa.For example, the manager and directReports properties extend the user resource to provide organizational hierarchy.

Las relaciones también definen las 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.Relationships also define memberships, such as the groups a user belongs to, the members belonging to a group or a directory role, and so on.

Solicitudes de Azure AD Graph use $link para indicar relaciones entre recursos.Azure AD Graph requests use $link to indicate relationships between resources. En Microsoft Graph, se usa la notación de ODATA 4,01 en $ref su lugar.In Microsoft Graph this uses the ODATA 4.01 $ref notation instead.

En la siguiente tabla se muestran varios ejemplos:The following table shows several examples:

TaskTask Azure AD GraphAzure AD Graph Microsoft GraphMicrosoft Graph
Agregar miembroAdd member POST /groups/{id}/$link/members POST /groups/{id}/members/$ref
Lista de vínculos de miembrosList member links GET /groups/{id}/$link/members GET /groups/{id}/members/$ref
Enumerar miembrosList members GET /groups/{id}/members GET /groups/{id}/members
Quitar miembroRemove member DELETE /groups/{id}/$link/members/{id} DELETE /groups/{id}/members/{id}/$ref

Al migrar las aplicaciones a Microsoft Graph, busque las solicitudes que usan $link para asociar recursos; cámbielas para usarlas en $ref su lugar.When migrating your apps to Microsoft Graph, look for requests that use $link to associate resources; change these to use $ref instead.

Siguientes pasosNext Steps