Procedimientos para: Usar Graph API de Azure ADHow to: Use the Azure AD Graph API

Graph API de Azure Active Directory (Azure AD) proporciona acceso mediante programación a Azure AD a través de los puntos de conexión de la API REST OData.The Azure Active Directory (Azure AD) Graph API provides programmatic access to Azure AD through OData REST API endpoints. Las aplicaciones pueden usar Graph API de Azure AD para ejecutar operaciones de creación, lectura, actualización y eliminación (CRUD) en objetos y datos de directorio.Applications can use Azure AD Graph API to perform create, read, update, and delete (CRUD) operations on directory data and objects. Por ejemplo, Graph API de Azure AD se puede usar para crear un nuevo usuario, ver o actualizar las propiedades de un usuario, cambiar la contraseña de un usuario, comprobar la pertenencia al grupo para el acceso basado en roles y deshabilitar o eliminar el usuario.For example, you can use Azure AD Graph API to create a new user, view or update user’s properties, change user’s password, check group membership for role-based access, disable, or delete the user. Para más información sobre los escenarios de aplicaciones y características de Graph API de Azure AD, consulte Graph API de Azure AD y los requisitos previos de Graph API de Azure AD.For more information on Azure AD Graph API features and application scenarios, see Azure AD Graph API and Azure AD Graph API Prerequisites.

Este artículo se aplica a Azure AD Graph API.This article applies to Azure AD Graph API. Para obtener información similar relacionada con Microsoft Graph API, consulte Usar la API de Microsoft Graph.For similar info related to Microsoft Graph API, see Use the Microsoft Graph API.

Importante

Se recomienda encarecidamente que utilice Microsoft Graph en lugar de Graph API de Azure AD para tener acceso a recursos de Azure Active Directory.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources. Nuestros esfuerzos de desarrollo ahora se centran en Microsoft Graph y no están previstas realizar mejoras adicionales para Graph API de Azure AD.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API. Hay un número muy limitado de escenarios para los que Azure AD Graph API todavía podría ser adecuado. Para obtener más información, consulte la entrada de blog Microsoft Graph o Azure AD Graph del centro de desarrollo de Office.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Construcción de una dirección URL de Graph APIHow to construct a Graph API URL

En Graph API, para tener acceso a los datos y objetos de los directorios (en otras palabras, a los recursos o entidades) con los que desee realizar operaciones CRUD, puede usar direcciones URL basadas en el protocolo Open Data (OData) Protocol.In Graph API, to access directory data and objects (in other words, resources or entities) against which you want to perform CRUD operations, you can use URLs based on the Open Data (OData) Protocol. Las direcciones URL que se usan en Graph API constan de cuatro partes principales: raíz del servicio, identificador de inquilino, ruta de acceso a recursos y opciones de cadena de consulta: https://graph.windows.net/{tenant-identifier}/{resource-path}?[query-parameters].The URLs used in Graph API consist of four main parts: service root, tenant identifier, resource path, and query string options: https://graph.windows.net/{tenant-identifier}/{resource-path}?[query-parameters]. Tome como ejemplo la siguiente dirección URL: https://graph.windows.net/contoso.com/groups?api-version=1.6.Take the example of the following URL: https://graph.windows.net/contoso.com/groups?api-version=1.6.

  • Raíz del servicio: en Graph API de Azure AD, la raíz del servicio es siempre https://graph.windows.net.Service Root: In Azure AD Graph API, the service root is always https://graph.windows.net.
  • Identificador de inquilino: esta sección puede ser un nombre de dominio (registrado) comprobado; en el ejemplo anterior, contoso.com.Tenant identifier: This section can be a verified (registered) domain name, in the preceding example, contoso.com. También puede ser un identificador de objeto de inquilino o los alias "myorganization" o "me".It can also be a tenant object ID or the “myorganization” or “me” alias. Para más información, consulte Información general de las operaciones | Conceptos de Graph API.For more information, see Addressing Entities and Operations in Azure AD Graph API.
  • Ruta de acceso del recurso: esta sección de una dirección URL identifica el recurso con el que se va a interactuar (usuarios, grupos, un usuario concreto o un grupo determinado, etc.) En el ejemplo anterior, son los "grupos" de nivel superior a los que se dirige este conjunto de recursos.Resource path: This section of a URL identifies the resource to be interacted with (users, groups, a particular user, or a particular group, etc.) In the example above, it is the top level “groups” to address that resource set. También se puede dirigir una entidad concreta, como por ejemplo, “users/{objectId}” o “users/userPrincipalName”.You can also address a specific entity, for example “users/{objectId}” or “users/userPrincipalName”.
  • Parámetros de consulta: un signo de interrogación (?) separa la sección de ruta de acceso a recursos de la sección de parámetros de consulta.Query parameters: A question mark (?) separates the resource path section from the query parameters section. Todas las solicitudes de Graph API de Azure AD requieren el parámetro de consulta "api-version".The “api-version” query parameter is required on all requests in Azure AD Graph API. Graph API de Azure AD también admite las siguientes opciones de consulta de OData: $filter, $orderby, $expand, $top y $format.Azure AD Graph API also supports the following OData query options: $filter, $orderby, $expand, $top, and $format. Sin embargo, las siguientes opciones de consulta no están admitidas actualmente: $count, $inlinecount y $skip.The following query options are not currently supported: $count, $inlinecount, and $skip. Para obtener más información, consulte Consultas admitidas, filtros y opciones de paginación en Graph API de Azure AD.For more information, see Supported Queries, Filters, and Paging Options in Azure AD Graph API.

Versiones de Graph APIGraph API versions

La versión de las solicitudes de Graph API se especifica en el parámetro de consulta "api-version".You specify the version for a Graph API request in the “api-version” query parameter. En el caso de la versión 1.5 y posterior, use un valor de versión numérico; api-version=1.6.For version 1.5 and later, you use a numerical version value; api-version=1.6. En el caso de versiones anteriores, use una cadena de fecha que se ajuste al formato AAAA-MM-DD; por ejemplo, api-version=2013-11-08.For earlier versions, you use a date string that adheres to the format YYYY-MM-DD; for example, api-version=2013-11-08. Para las características de vista previa, use la cadena "beta"; por ejemplo, api-version = beta.For preview features, use the string “beta”; for example, api-version=beta. Para más información sobre las diferencias entre las distintas versiones de Graph API, consulte Control de versiones de Graph API de Azure AD.For more information about differences between Graph API versions, see Azure AD Graph API Versioning.

Metadatos de Graph APIGraph API metadata

Para devolver el archivo de metadatos de Graph API de Azure AD, agregue el segmento "$metadata" después del identificador de inquilino en la dirección URL. Por ejemplo, la dirección URL siguiente devuelve los metadatos de la compañía de demostración: https://graph.windows.net/GraphDir1.OnMicrosoft.com/$metadata?api-version=1.6.To return the Azure AD Graph API metadata file, add the “$metadata” segment after the tenant-identifier in the URL For example, the following URL returns metadata for a demo company: https://graph.windows.net/GraphDir1.OnMicrosoft.com/$metadata?api-version=1.6. Puede escribir esta dirección URL en la barra de direcciones de un explorador web para ver los metadatos.You can enter this URL in the address bar of a web browser to see the metadata. El documento de metadatos CSDL devuelto describe las entidades y los tipos complejos, sus propiedades, y las funciones y acciones expuestas por la versión de Graph API que ha solicitado.The CSDL metadata document returned describes the entities and complex types, their properties, and the functions and actions exposed by the version of Graph API you requested. Si se omite el parámetro api-version se devolverán los metadatos de la versión más reciente.Omitting the api-version parameter returns metadata for the most recent version.

Consultas comunesCommon queries

Consultas comunes de Graph API de Azure AD: se enumeran las consultas comunes que pueden usarse con Azure AD Graph, incluidas las consultas que pueden usarse para obtener acceso a recursos de nivel superior del directorio y las consultas para realizar operaciones en el directorio.Azure AD Graph API Common Queries lists common queries that can be used with the Azure AD Graph, including queries that can be used to access top-level resources in your directory and queries to perform operations in your directory.

Por ejemplo, https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 devuelve la información de la compañía en el directorio contoso.com.For example, https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 returns company information for directory contoso.com.

O, https://graph.windows.net/contoso.com/users?api-version=1.6 enumera todos los objetos de usuario del directorio de contoso.com.Or https://graph.windows.net/contoso.com/users?api-version=1.6 lists all user objects in the directory contoso.com.

Uso del Probador de Graph de Azure ADUsing the Azure AD Graph Explorer

El Probador de Graph de Azure AD se puede usar para que Graph API de Azure AD consulte los datos de directorio al compilar la aplicación.You can use the Azure AD Graph Explorer for the Azure AD Graph API to query the directory data as you build your application.

En la captura de pantalla siguiente se muestra el resultado que vería si fuera al Probador de Graph de Azure AD, iniciara y escribiera https://graph.windows.net/GraphDir1.OnMicrosoft.com/users?api-version=1.6 para mostrar todos los usuarios del directorio del usuario que ha iniciado sesión:The following screenshot is the output you would see if you were to navigate to the Azure AD Graph Explorer, sign in, and enter https://graph.windows.net/GraphDir1.OnMicrosoft.com/users?api-version=1.6 to display all the users in the signed-in user's directory:

Salida de ejemplo en Azure AD Graph API Explorer

Carga de Azure AD Graph Explorer: para cargar la herramienta, vaya a https://graphexplorer.azurewebsites.net/ .Load the Azure AD Graph Explorer: To load the tool, navigate to https://graphexplorer.azurewebsites.net/. Haga clic en Iniciar sesión e inicie sesión con las credenciales de su cuenta de Azure AD para ejecutar el Probador de Graph de Azure AD con el inquilino.Click Login and sign-in with your Azure AD account credentials to run the Azure AD Graph Explorer against your tenant. Si ejecuta el Probador de Graph de Azure AD con su propio inquilino, usted o el administrador tendrán que dar su consentimiento durante el inicio de sesión.If you run Azure AD Graph Explorer against your own tenant, either you or your administrator needs to consent during sign-in. Si dispone de una suscripción a Office 365, tendrá automáticamente un inquilino de Azure AD.If you have an Office 365 subscription, you automatically have an Azure AD tenant. De hecho, las credenciales que usa para iniciar sesión en Office 365 son cuentas de Azure AD y puede usarlas con el Probador de Graph de Azure AD.The credentials you use to sign in to Office 365 are, in fact, Azure AD accounts, and you can use these credentials with Azure AD Graph Explorer.

Ejecutar una consulta: para ejecutar una consulta, escríbala en el cuadro de texto de la solicitud y haga clic en GET o en la tecla Entrar.Run a query: To run a query, type your query in the request text box and click GET or click the enter key. Los resultados se muestran en el cuadro de respuesta.The results are displayed in the response box. Por ejemplo, https://graph.windows.net/myorganization/groups?api-version=1.6 enumera todos los objetos de grupo del directorio del usuario que ha iniciado sesión.For example, https://graph.windows.net/myorganization/groups?api-version=1.6 lists all group objects in the signed-in user's directory.

Tenga en cuenta las siguientes características y limitaciones del Probador de Graph de Azure AD:Note the following features and limitations of the Azure AD Graph Explorer:

  • Funcionalidad Autocompletar en conjuntos de recursos.Autocomplete capability on resource sets. Para ver esta funcionalidad, haga clic en el cuadro de texto de la solicitud (donde aparece la dirección URL de la compañía).To see this functionality, click on the request text box (where the company URL appears). Puede seleccionar un conjunto de recursos en la lista desplegable.You can select a resource set from the dropdown list.
  • Historial de solicitudes.Request history.
  • Admite los alias de direccionamiento “me” y “myorganization”.Supports the “me” and “myorganization” addressing aliases. Por ejemplo, puede usar https://graph.windows.net/me?api-version=1.6 para devolver el objeto de usuario del usuario con sesión iniciada o https://graph.windows.net/myorganization/users?api-version=1.6 para devolver todos los usuarios del directorio del usuario con sesión iniciada.For example, you can use https://graph.windows.net/me?api-version=1.6 to return the user object of the signed-in user or https://graph.windows.net/myorganization/users?api-version=1.6 to return all users in the signed-in user's directory.
  • Admite operaciones de creación, lectura, actualización y eliminación (CRUD) completas en su propio directorio con POST, GET, PATCH y DELETE.Supports full CRUD operations against your own directory using POST, GET, PATCH and DELETE.
  • Una sección de encabezados de respuesta.A response headers section. Esta sección se puede usar como ayuda para solucionar los problemas que se producen al ejecutar consultas.This section can be used to help troubleshoot issues that occur when running queries.
  • Un visor JSON para la respuesta con capacidades de expansión y contracción.A JSON viewer for the response with expand and collapse capabilities.
  • No permite mostrar o cargar fotos en miniatura.No support for displaying or uploading a thumbnail photo.

Uso de Fiddler para escribir en el directorioUsing Fiddler to write to the directory

Para seguir esta guía de inicio rápido, puede usar el depurador web Fiddler para practicar la realización de operaciones de "escritura" con su directorio de Azure AD.For the purposes of this Quickstart guide, you can use the Fiddler Web Debugger to practice performing ‘write’ operations against your Azure AD directory. Por ejemplo, puede obtener y cargar la foto del perfil de un usuario (lo cual no es posible con el Probador de Graph de Azure AD).For example, you can get and upload a user's profile photo (which is not possible with Azure AD Graph Explorer). Para obtener más información y para instalar Fiddler, consulte https://www.telerik.com/fiddler.For more information and to install Fiddler, see https://www.telerik.com/fiddler.

En el ejemplo siguiente, usará el depurador web Fiddler para crear un nuevo grupo de seguridad, "MyTestGroup", en el directorio de Azure AD.In the example below, you use Fiddler Web Debugger to create a new security group ‘MyTestGroup’ in your Azure AD directory.

Obtener un token de acceso: para obtener acceso a Azure AD Graph, los clientes deben autenticarse primero correctamente en Azure AD.Obtain an access token: To access Azure AD Graph, clients are required to successfully authenticate to Azure AD first. Para obtener más información, consulte Escenarios de autenticación en Azure AD.For more information, see Authentication Scenarios for Azure AD.

Redactar y ejecutar una consulta: Complete los siguientes pasos:Compose and run a query: Complete the following steps:

  1. Abra el depurador web Fiddler y cambie a la pestaña Composer (Compositor).Open Fiddler Web Debugger and switch to the Composer tab.

  2. Puesto que desea crear un nuevo grupo de seguridad, seleccione Post como método de HTTP en el menú desplegable.Since you want to create a new security group, select Post as the HTTP method from the pull-down menu. Para más información sobre las operaciones y los permisos de los objetos de grupo, consulte la sección sobre los grupos en la referencia sobre la API de REST Graph de Azure AD.For more information about operations and permissions on a group object, see Group within the Azure AD Graph REST API Reference.

  3. En el campo que se encuentra junto a Post, escriba la siguiente dirección URL de solicitud: https://graph.windows.net/{mytenantdomain}/groups?api-version=1.6.In the field next to Post, type in the following request URL: https://graph.windows.net/{mytenantdomain}/groups?api-version=1.6.

    Nota

    Debe sustituir {mytenantdomain} por el nombre de dominio de su directorio de Azure AD.You must substitute {mytenantdomain} with the domain name of your own Azure AD directory.

  4. En el campo que se encuentra inmediatamente debajo de Post, escriba el siguiente encabezado HTTP:In the field directly below Post pull-down, type the following HTTP header:

    Host: graph.windows.net
    Authorization: Bearer <your access token>
    Content-Type: application/json
    

    Nota

    Sustituya <su token de acceso> por el del directorio de Azure AD.Substitute your <your access token> with the access token for your Azure AD directory.

  5. En el campo Cuerpo de la solicitud escriba el siguiente JSON:In the Request body field, type the following JSON:

        {
            "displayName":"MyTestGroup",
            "mailNickname":"MyTestGroup",
            "mailEnabled":"false",
            "securityEnabled": true
        }
    

    Para más información sobre la creación de grupos, consulte Crear un grupo.For more information about creating groups, see Create Group.

Para más información sobre las entidades y los tipos de Azure AD expuestos por Graph, así como sobre las operaciones que se pueden realizar en ellos con Graph, consulte Referencia de la API Graph de Azure AD.For more information on Azure AD entities and types that are exposed by Graph and information about the operations that can be performed on them with Graph, see Azure AD Graph REST API Reference.

Pasos siguientesNext steps