Información general de las operaciones | Conceptos de Graph API

  • Artículo

La API de Azure Active Directory (AD) Graph es un servicio compatible con OData 3.0 que puede usar para leer y modificar objetos como usuarios, grupos y contactos en un inquilino. La API de Azure AD Graph expone los puntos de conexión de REST a los que se envían solicitudes HTTP para realizar operaciones mediante el servicio. En las siguientes secciones se proporciona información general sobre cómo dar formato a las solicitudes y qué esperar en las respuestas cuando usa Graph API para leer y escribir recursos de directorio, llamar a acciones o funciones de directorio o realizar consultas en el directorio. Para obtener más información sobre cómo realizar operaciones específicas en los recursos de directorio, consulte el tema de operaciones adecuado en la referencia de la API de Azure AD Graph.

Importante

Se recomienda encarecidamente que use Microsoft Graph en lugar de la API de Azure AD Graph para acceder a recursos de Azure Active Directory. Nuestros esfuerzos de desarrollo se concentran ahora en Microsoft Graph y no están previstas mejoras adicionales para la API de Azure AD Graph. Hay un número muy limitado de escenarios para los que la API de Azure AD Graph todavía podría ser adecuada; para más información, vea la entrada del blog Microsoft Graph o Azure AD Graph en el centro de desarrollo de Office.

Una solicitud correcta a Graph API se debe dirigir a un punto de conexión válido y debe tener un formato adecuado, es decir, debe contener los encabezados necesarios y, si corresponde, una carga JSON en el cuerpo de la solicitud. La aplicación que realiza la solicitud debe incluir un token que recibe de Azure AD y que comprueba que está autorizada a tener acceso a los recursos a los que se dirige la solicitud. La aplicación debe poder controlar las respuestas que se reciben desde Graph API.

Las secciones de este tema le ayudarán a comprender el formato de las solicitudes y las respuestas que se usa con Graph API.

Autenticación y autorización

Cada solicitud que se envía a Graph API debe tener un token de portador emitido por una instancia de Azure Active Directory adjunta. El token transporta información sobre la aplicación, el usuario con sesión iniciada (en caso de que se trate de permisos delegados), autenticación y las operaciones que se realizan en el directorio en el que la aplicación está autorizada para realizarlas. Este token se incluye en el encabezado Authorization de la solicitud. Por ejemplo (el token se abrevió por razones de espacio):

Authorization: Bearer eyJ0eX ... FWSXfwtQ

Graph API realiza la autorización en función de los ámbitos de permiso de OAuth 2.0 presentes en el token. Para obtener más información sobre los ámbitos de permiso que expone Graph API, consulte Ámbitos de permiso de Graph API.

Con el fin de autenticar la aplicación con Azure AD y llamar a Graph API, se la debe agregar al inquilino y configurarla para requerir permisos (ámbitos de permiso de OAuth 2.0) para Microsoft Azure Active Directory. Para obtener información sobre cómo agregar y configurar una aplicación, consulte Integración de aplicaciones con Azure Active Directory.

Azure AD usa el protocolo de autenticación de OAuth 2.0. Puede obtener más información sobre OAuth 2.0 en Azure AD, incluidos los flujos compatibles y los tokens de acceso en OAuth 2.0 en Azure AD.

Direccionamiento de puntos de conexión

Para realizar operaciones con Graph API, se envían solicitudes HTTP con un método compatible, habitualmente GET, POST, PATCH, PUT o DELETE, a un punto de conexión que se dirige al servicio, una colección de recursos, un recurso individual, una propiedad de navegación de un recurso o una función o acción que el servicio expone. Los puntos de conexión se expresan como direcciones URL.

A continuación, se describe el formato básico de un punto de conexión de Graph API:

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}

Los siguientes componentes conforman la dirección URL:

Nota: En algunos casos, cuando se leen las colecciones de recursos, se pueden agregar los parámetros de consulta OData a la solicitud para filtrar, ordenar y paginar el conjunto de resultados. Para más información, consulte la sección Parámetros de consulta OData de este tema.

Identificador de inquilino {tenant_id}

Puede especificar el inquilino de destino de una solicitud de una de las siguientes cuatro maneras:

  • Por identificador de objeto de inquilino. El GUID que se asignó al crear el inquilino. Se puede encontrar en la propiedad objectId del objeto TenantDetail. La dirección URL siguiente muestra cómo abordar la colección de recursos de usuarios a través del identificador de objeto de inquilino:
    https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.

  • Por nombre de dominio comprobado (registrado). Uno de los nombres de dominio registrado para el inquilino. Se pueden encontrar en la propiedad verifiedDomains del objeto TenantDetail. La dirección URL siguiente muestra cómo abordar la colección de recursos de usuarios de un inquilino que tiene el dominio contoso.com:
    https://graph.windows.net/contoso.com/users?api-version=1.6.

  • Mediante el uso del alias myOrganization. Este alias está disponible solo cuando se usa la autenticación de tipo de concesión de código de autorización OAuth (3 segmentos), es decir, cuando se usa un ámbito de permiso delegado. El alias no distingue mayúsculas de minúsculas. Reemplaza el identificador de objeto o el dominio de inquilino en la dirección URL. Cuando se usa el alias, Graph API deriva el inquilino desde las notificaciones presentadas en el token adjunto a una solicitud. La dirección URL siguiente muestra cómo abordar la colección de recursos de usuarios de un inquilino mediante este alias:
    https://graph.windows.net/myorganization/users?api-version=1.6.

  • Mediante el uso del alias me. Este alias está disponible solo cuando se usa la autenticación de tipo de concesión de código de autorización OAuth (3 segmentos), es decir, cuando se usa un ámbito de permiso delegado. El alias no distingue mayúsculas de minúsculas. Reemplaza el identificador de objeto o el dominio de inquilino en la dirección URL. Cuando se usa el alias, Graph API deriva el usuario desde las notificaciones presentadas en el token adjunto a la solicitud. La dirección URL siguiente muestra cómo abordar al usuario con sesión iniciada mediante este alias:
    https://graph.windows.net/me?api-version=1.6.

Nota: El alias me se usa únicamente para dirigirse a las operaciones en el usuario con sesión iniciada. Para más información, consulte Operaciones de usuario con sesión iniciada.

Ruta de acceso al recurso {resource_path}

La {resource_path} se especifica de manera distinta según si se dirige a una colección de recursos, un recurso individual, una propiedad de navegación de un recurso, una función o acción que se expone en el inquilino o una función o acción que se expone en un recurso.

Destino Ruta de acceso Explicación
Metadatos de servicio /$metadata Devuelve el documento de metadatos de servicio. El ejemplo siguiente se dirige a los metadatos de servicio con el inquilino contoso.com:
https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Nota: No se necesita realizar la autenticación para leer los metadatos de servicio.
Colección de recursos /{resource_collection} Se dirige a una colección de recursos, como usuarios o grupos en el inquilino. Puede usar esta ruta de acceso para leer los recursos de la colección y, según el tipo de recurso, para crear un recurso nuevo en el inquilino. En muchos casos, el conjunto de resultados que una lectura devuelve se puede restringir aún más si se agregan parámetros de consulta para filtrar, ordenar o paginar los resultados. El ejemplo siguiente se orienta a la colección de usuarios:
https://graph.windows.net/myorganization/users?api-version=1.6
Recurso único /{resource_collection}/{resource_id} Se dirige a un recurso específico en un inquilino, como un usuario, un contacto organizacional o un grupo. En la mayoría de los recursos, el resource_id es el identificador de objeto. Algunos recursos permiten especificadores adicionales; por ejemplo, también se pueden especificar a los usuarios por nombre principal de usuario (UPN). Según el recurso, puede usar esta ruta de acceso para obtener las propiedades declaradas del recurso, modificar las propiedades declaradas o eliminar el recurso. El ejemplo siguiente se dirige al usuario john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6
Propiedad de navegación (objetos) /{resource_collection}/{resource_id}/{property_name} Se dirige a una propiedad de navegación de un recurso específico, como el administrador o las pertenencias a grupos de un usuario o los miembros de un grupo. Puede usar esta ruta de acceso para devolver el objeto o los objetos a los que hace referencia la propiedad de navegación de destino. El ejemplo siguiente se dirige al administrador de john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6

Nota: Esta forma de direccionamiento solo está disponible para lecturas.
Propiedad de navegación (vínculos) /{resource_collection}/{resource_id}/$links/{property_name} Se dirige a una propiedad de navegación de un recurso específico, como el administrador o las pertenencias a grupos de un usuario o los miembros de un grupo. Puede usar esta forma de direccionamiento tanto para leer como para modificar una propiedad de navegación. En las lecturas, los objetos a los que hace referencia la propiedad se devuelven como uno o varios vínculos en el cuerpo de respuesta. En las escrituras, los objetos se especifican como uno o varios vínculos en el cuerpo de la solicitud. El ejemplo siguiente se dirige a la propiedad del administrador de john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6
Funciones o acciones expuestas en el inquilino /{function_name} Se dirige a una función o acción que se expone en el inquilino. Las funciones y acciones se invocan habitualmente con una solicitud POST y pueden incluir un cuerpo de solicitud. El ejemplo siguiente se dirige a la función isMemberOf:
https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.
Funciones o acciones expuestas en un recurso /{resource_collection}/{resource_id}/{function_name} Se dirige a una función o acción que se expone en un recurso Las funciones y acciones se invocan habitualmente con una solicitud POST y pueden incluir un cuerpo de solicitud. El ejemplo siguiente se dirige a la función getMemberGroups:
https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.

Versión de Graph API {api-version}

El parámetro de consulta api-version se usa para dirigirse a una versión específica de Graph API de una operación. Este parámetro es obligatorio.

El parámetro api-version puede tener uno de los siguientes valores:

  • "beta"
  • "1.6"
  • "1.5"
  • "2013/11/08"
  • "2013/04/05"

Por ejemplo, la dirección URL siguiente se dirige a la colección de usuarios con la versión 1.6 de Graph API:

https://graph.windows.net/myorganization/users?api-version=1.6

Para más información sobre las versiones y los cambios de características entre las versiones, consulte Control de versiones.

Parámetros de consulta OData

En muchos casos, cuando lee una colección de recursos, puede filtrar, ordenar y paginar el conjunto de resultados si adjunta los parámetros de consulta OData a la solicitud.

Graph API admite los siguientes parámetros de consulta OData:

  • $filter
  • $batch
  • $expand
  • $orderby
  • $top
  • $skiptoken y previous-page

Consulte Consultas, filtros y opciones de paginación admitidos para obtener más información sobre los parámetros de consulta OData compatibles y sus limitaciones en Graph API.

Encabezados de solicitud y respuesta

En la tabla siguiente se muestran los encabezados HTTP comunes que se usan en las solicitudes con Graph API. No pretende ser exhaustiva.

Encabezado de solicitud Descripción
Autorización Obligatorio. Un token de portador emitido por Azure Active Directory. Consulte Autenticación y autorización en este tema para obtener más información.
Content-Type Obligatorio si está presente el cuerpo de la solicitud. El tipo de medio del contenido en el cuerpo de la solicitud. Use application/json. Se pueden incluir parámetros con el tipo de medio.
Nota: application/atom+xml y application/xml (para vínculos) son compatibles pero no se recomiendan por motivos de rendimiento y porque la compatibilidad con XLM quedará en desuso en una futura versión.
Content-Length Obligatorio si está presente el cuerpo de la solicitud. La longitud de la solicitud en bytes.

En la tabla siguiente se muestran los encabezados HTTP comunes que Graph API devuelve en las respuestas. No pretende ser exhaustiva.

Encabezado de respuesta Descripción
Content-Type El tipo de medio del contenido en el cuerpo de la respuesta. El valor predeterminado es application/json. Las solicitudes de fotos del usuario en miniatura devuelven image/jpeg de manera predeterminada.
Ubicación Se devuelve en respuestas a las solicitudes POST que crean un recurso (objeto) nuevo en el directorio. Contiene el URI del recurso creado recientemente.
ocp-aad-diagnostics-server-name El identificador del servidor que realizó la operación solicitada.
ocp-aad-session-key La clave que identifica la sesión actual con el servicio de directorio.

Como mínimo, se recomienda que realice lo siguiente para cada solicitud:

  1. Registrar una marca de tiempo precisa del envío de la solicitud.
  2. Enviar y registrar el client-request-id.
  3. Registrar el código de la respuesta HTTP y request-id.

Proporcionar información en dichos registros permitirá que Microsoft solucione problemas cuando se le solicite ayuda o soporte técnico.

Cuerpos de solicitud y respuesta

Se pueden enviar cuerpos de solicitud para solicitudes POST, PATCH y PUT en cargas JSON o XML. Las respuestas del servidor se pueden devolver en cargas JSON o XML. Puede especificar la carga en los cuerpos de la solicitud; para ello, use el encabezado de solicitud Content-Type y, en las respuestas, el encabezado de solicitud Accept.

Se recomienda el uso de cargas JSON en solicitudes y respuestas con Graph API. Esto es así por motivos de rendimiento y porque la compatibilidad con XML quedará en desuso en una futura versión.

Características avanzadas

En las secciones anteriores se analizó el formato de las solicitudes y respuestas básicas con Graph API. Otras características avanzadas pueden agregar parámetros de cadena de consulta adicionales o pueden tener cuerpos de solicitud y respuesta considerablemente distintos a las operaciones básicas que se analizaron anteriormente en este tema.

Estas características incluyen:

  • Procesamiento por lotes: Graph API es compatible con el procesamiento por lotes. El envío de solicitudes en lotes reduce los recorridos de ida y vuelta al servidor, lo que disminuye la sobrecarga de la red y permite que las operaciones se completen más rápido. Para obtener más información acerca del procesamiento por lotes con Graph API, consulte Procesamiento por lotes.
  • Consulta diferencial: Graph API es compatible con la realización de consultas diferenciales. La consulta diferencial permite devolver cambios a entidades específicas de un inquilino entre las solicitudes emitidas en distintos momentos. Con frecuencia, esta característica se usa para sincronizar un almacén local con los cambios realizados en el inquilino. Para obtener más información sobre la consulta diferencial con Graph API, consulte Consulta diferencial.

Recursos adicionales