Obtener acceso a datos y métodos al navegar por Microsoft GraphAccess data and methods by navigating Microsoft Graph

Además de utilizar la API de Microsoft Graph para leer y escribir datos, puede utilizar una serie de modelos de solicitud para realizar un recorrido entre los recursos de Microsoft Graph. El documento de metadatos también le ayuda a entender el modelo de datos de los recursos y las relaciones en Microsoft Graph.In addition to using the Microsoft Graph API to read and write data, you can use a number of request patterns to traverse through the resources in Microsoft Graph. The metadata document also helps you to understand the data model of the resources and relationships in Microsoft Graph.

Metadatos de la API de Microsoft GraphMicrosoft Graph API metadata

El documento de metadatos ($metadata) se publica en la raíz del servicio. Puede ver el documento de servicio para las versiones v1.0 y beta de la API de Microsoft Graph a través de las siguientes URL.The metadata document ($metadata) is published at the service root. You can view the service document for the v1.0 and beta versions of the Microsoft Graph API via the following URLs.

Metadatos de Microsoft Graph API v1.0Microsoft Graph API v1.0 metadata

    https://graph.microsoft.com/v1.0/$metadata

Metadatos beta de la API de Microsoft GraphMicrosoft Graph API beta metadata

    https://graph.microsoft.com/beta/$metadata

Los metadatos le permiten ver y entender el modelo de datos de Microsoft Graph, incluidos los tipos de entidades, los tipos complejos y las enumeraciones que conforman los recursos que se representan en los paquetes de respuesta y solicitud.The metadata allows you to see and understand the Microsoft Graph data model, including the entity types, complex types, and enumerations that make up the resources represented in the request and response packets.

Los metadatos también admiten la definición de tipos, los métodos y las enumeraciones en los nombres de espacios de OData correspondientes.The metadata also supports defining types, methods, and enumerations in corresponding OData namespaces. La mayor parte de la API de Microsoft Graph se define en el nombre de espacios de OData, microsoft.graph.The majority of the Microsoft Graph API is defined in the OData namespace, microsoft.graph.

Puede usar los metadatos para conocer las relaciones entre las entidades en Microsoft Graph y establecer las URL que navegarán entre dichas entidades.You can use the metadata to learn the relationships between entities in Microsoft Graph and establish URLs that navigate between those entities.

Nota

  • Use los Id. de recursos en el mismo caso en el que se devuelven desde las API de Microsoft Graph.Use resource IDs in the same case as they are returned from Microsoft Graph APIs.
  • Suponga que los Id. de recursos, los valores que asigne y otros valores codificados en base 64 distinguen entre mayúsculas y minúsculas.Assume resource IDs, values you assign, and other base-64-encoded values are case-sensitive.
  • Supongamos que la URL de la ruta de acceso, parámetros de consulta, nombres de acción y de función, los parámetros del cuerpo de la solicitud, incluidos los nombres y valores de propiedades de API, no distinguen mayúsculas de minúsculas.Assume path URL resource names, query parameters, action and function names, their request body parameters, including any API property names and values, are not case-sensitive.

Ver una colección de recursosView a collection of resources

Microsoft Graph permite ver recursos en un espacio empresarial mediante consultas HTTP GET.Microsoft Graph lets you view resources in a tenant using HTTP GET queries. La respuesta de la consulta incluye las propiedades de cada recurso.The query response includes properties of each resource. Cada uno de los recursos de la entidad se identifica por su ID.Entity resources are each identified by its ID. El formato de un id. de recurso puede ser un GUID y por lo general varía según el tipo de recurso.The format of a resource ID can be a GUID, and generally varies according to the resource type.

Por ejemplo, puede obtener la colección de recursos del user que se define en un espacio empresarial:For example, you can get the collection of user resources defined in a tenant:

GET https://graph.microsoft.com/v1.0/users HTTP/1.1
Authorization : Bearer {access_token}

Si es correcto, se obtendrá una respuesta 200 OK que contiene la colección de recursos del usuario en la carga. Cada usuario está identificado por la propiedad id y va acompañado de sus propiedades predeterminadas. Para una mayor brevedad, la carga que se muestra a continuación se trunca.If successful, you'll get a 200 OK response that contains the collection of user resources in the payload. Each user is identified by the id property and accompanied by its default properties. The payload shown below is truncated for brevity.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "value":[
    {
      "id":"f71f1f74-bf1f-4e6b-b266-c777ea76e2c7",
      "businessPhones":[

      ],
      "displayName":"CIE Administrator",
      "givenName":"CIE",
      "jobTitle":null,
      "mail":"admin@contoso.onmicrosoft.com",
      "mobilePhone":"+1 3528700812",
      "officeLocation":null,
      "preferredLanguage":"en-US",
      "surname":"Administrator",
      "userPrincipalName":"admin@contoso.onmicrosoft.com"
    },
    {
      "id":"d66f2902-9d12-4ff8-ab01-21ec6706079f",
      "businessPhones":[

      ],
      "displayName":"Alan Steiner",
      "givenName":"Alan",
      "jobTitle":"VP Corporate Marketing",
      "mail":"alans@contoso.onmicrosoft.com",
      "mobilePhone":null,
      "officeLocation":null,
      "preferredLanguage":"en-US",
      "surname":"Steiner",
      "userPrincipalName":"alans@contoso.onmicrosoft.com"
    }
  ]
}

Microsoft Graph también permite ver las colecciones mediante la exploración de las relaciones entre recursos. Por ejemplo, a través de la propiedad de navegación mailFolders de un usuario, se puede realizar una consulta en la colección de recursos mailFolder del buzón de correo del usuario:Microsoft Graph also lets you view collections by navigating the relationships of one resource with another. For example, through a user's mailFolders navigation property, you can query for the collection of mailFolder resources in the user's mailbox:

GET https://graph.microsoft.com/v1.0/me/mailfolders HTTP/1.1
Authorization : Bearer {access_token}

Si es correcta, se obtendrá una respuesta 200 OK que contiene la colección de recursos de mailFolder en la carga. Cada mailFolder está identificada por la propiedad id y va acompañada de sus propiedades predeterminadas. Para una mayor brevedad, la carga que se muestra a continuación se trunca.If successful, you'll get a 200 OK response that contains the collection of mailFolder resources in the payload. Each mailFolder is identified by the id property and accompanied by its properties. The payload shown below is truncated for brevity.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('16f5a7b6-5a15-4568-aa5a-31bb117e9967')/mailFolders",
  "value":[
    {
      "id":"AAMkADRm9AABDGisXAAA=",
      "displayName":"Archive",
      "parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
      "childFolderCount":0,
      "unreadItemCount":0,
      "totalItemCount":0
    },
    {
      "id":"AQMkADRm0AAAIBXAAAAA==",
      "displayName":"Sales reports",
      "parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
      "childFolderCount":0,
      "unreadItemCount":0,
      "totalItemCount":0
    },
    {
      "id":"AAMkADRCxI9AAAT6CAIAAA=",
      "displayName":"Conversation History",
      "parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
      "childFolderCount":1,
      "unreadItemCount":0,
      "totalItemCount":0
    }
  ]
}

Ver un recurso específico de una colección por id.View a specific resource from a collection by ID

Continuando con el ejemplo del user, si se quiere ver la información sobre un usuario, se utiliza una solicitud HTTPS GET para obtener un usuario específico por el id. de usuario.Continuing with using user as an example - to view the information about a user, use an HTTPS GET request to get a specific user by the user's ID. Para una entidad user, puede usar como identificador la propiedad id o la propiedad userPrincipalName.For a user entity, you can use either the id or userPrincipalName property as the identifier.

En la solicitud de ejemplo siguiente se usa el valor userPrincipalName como id. del usuario.The following request example uses the userPrincipalName value as the user's ID.

GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.onmicrosoft.com HTTP/1.1
Authorization : Bearer {access_token}

Si es correcto, se obtendrá una respuesta 200 OK que contiene la representación de recursos del usuario en la carga, como se muestra.If successful, you'll get a 200 OK response that contains the user resource representation in the payload, as shown.

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 982

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "id": "c95e3b3a-c33b-48da-a6e9-eb101e8a4205",
    "city": "Redmond",
    "country": "USA",
    "department": "Help Center",
    "displayName": "John Doe",
    "givenName": "John",
    "userPrincipalName": "john.doe@contoso.onmicrosoft.com",

    ...
}

Lea las propiedades específicas de un recursoRead specific properties of a resource

Para recuperar tan solo los datos biográficos del usuario, como la descripción de Acerca de mí que proporcionó y su conjunto de aptitudes, puede agregar el parámetro de consulta $select a la solicitud anterior, como se muestra en el ejemplo siguiente:To retrieve only the user's biographical data, such as the user's provided About me description and their skill set, you can add the $select query parameter to the previous request, as shown in the following example.

GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.onmicrosoft.com?$select=displayName,aboutMe,skills HTTP/1.1
Authorization : Bearer {access_token}

La respuesta correcta devuelve el estado 200 OK y una carga en el formato siguiente, como se muestra.The successful response returns the 200 OK status and a payload, as shown.

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 169

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "aboutMe": "A cool and nice guy.",
    "displayName": "John Doe",
    "skills": [
        "n-Lingual",
        "public speaking",
        "doodling"
    ]
}

Aquí, en lugar de todos los conjuntos de propiedades de la entidad user, solo se devuelven las propiedades básicas aboutMe, displayName y skills.Here, instead of the entire property sets on the user entity, only the aboutMe, displayName, and skills basic properties are returned.

Leer las propiedades específicas de los recursos de una colecciónRead specific properties of the resources in a collection

Además de leer las propiedades específicas de un único recurso, también puede aplicar el parámetro de consulta similar $select a una colección para obtener de nuevo todos los recursos en la colección con tan solo las propiedades específicas en cada uno.In addition to reading specific properties of a single resource, you can also apply the similar $select query parameter to a collection to get back all resources in the collection with just the specific properties returned on each.

Por ejemplo, para consultar el nombre de los elementos de la unidad del usuario que ha iniciado sesión, se puede enviar la siguiente solicitud HTTPS GET:For example, to query the name of the signed-in user's drive items, you can submit the following HTTPS GET request.

GET https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name HTTP/1.1
Authorization : Bearer {access_token}

La respuesta correcta devuelve un código de estado 200 OK y una carga que contiene solamente los nombres y los tipos de los archivos compartidos, tal como se muestra en el ejemplo siguiente:The successful response returns a 200 OK status code and a payload that contains only the names of the shared files, as shown in the following example.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('john.doe%40contoso.onmicrosoft.com')/drive/root/children(name,type)",
  "value": [
    {
      "@odata.etag": "\"{896A8E4D-27BF-424B-A0DA-F073AE6570E2},2\"",
      "name": "Shared with Everyone"
    },
    {
      "@odata.etag": "\"{B39D5D2E-E968-491A-B0EB-D5D0431CB423},1\"",
      "name": "Documents"
    },
    {
      "@odata.etag": "\"{9B51EA38-3EE6-4DC1-96A6-230E325EF054},2\"",
      "name": "newFile.txt"
    }
  ]
}

Recorrido desde un recurso a otro a través de la relaciónTraverse from one resource to another via relationship

Un administrador mantiene una relación directReports con el resto de los usuarios a su cargo. Para consultar la lista de relaciones directas de un usuario, se puede usar la siguiente solicitud HTTPS GET para navegar hasta el destino deseado mediante un recorrido de relaciones.A manager holds a directReports relationship with the other users reporting to him or her. To query the list of the direct reports of a user, you can use the following HTTPS GET request to navigate to the intended target via relationship traversal.

GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.onmicrosoft.com/directReports HTTP/1.1
Authorization : Bearer {access_token}

La respuesta correcta devuelve el estado 200 OK y una carga, como se muestra.The successful response returns the 200 OK status and a payload, as shown.

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 152

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#directoryObjects/$entity",
    "@odata.type": "#microsoft.graph.user",
    "id": "c37b074d-fe9d-4e68-83ad-b4401d3be174",
    "department": "Sales & Marketing",
    "displayName": "Bonnie Kearney",

    ...
}

De forma similar, se puede seguir una relación para ir a los recursos relacionados. Por ejemplo, la relación usuario-mensajes permite un recorrido desde un usuario de Azure Active Directory (Azure AD) hasta un conjunto de mensajes de correo de Outlook. En el ejemplo siguiente se muestra cómo realizar esta acción en una llamada de la API de REST:Similarly, you can follow a relationship to navigate to related resources. For example, the user-messages relationship enables traversal from an Azure Active Directory (Azure AD) User to a set of Outlook mail messages. The following example shows how to do this in a REST API call.

GET https://graph.microsoft.com/v1.0/me/messages HTTP/1.1
Authorization : Bearer {access_token}

La respuesta correcta devuelve el estado 200 OK y una carga, como se muestra.The successful response returns the 200 OK status and a payload, as shown.

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
odata-version: 4.0
content-length: 147

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('john.doe%40contoso.onmicrosoft.com')/Messages",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$top=1&$skip=1",
  "value": [
    {
      "@odata.etag": "W/\"FwAAABYAAABMR67yw0CmT4x0kVgQUH/3AAJL+Kej\"",
      "id": "<id-value>",
      "createdDateTime": "2015-11-14T00:24:42Z",
      "lastModifiedDateTime": "2015-11-14T00:24:42Z",
      "changeKey": "FwAAABYAAABMR67yw0CmT4x0kVgQUH/3AAJL+Kej",
      "categories": [],
      "receivedDateTime": "2015-11-14T00:24:42Z",
      "sentDateTime": "2015-11-14T00:24:28Z",
      "hasAttachments": false,
      "subject": "Did you see last night's game?",
      "body": {
        "ContentType": "HTML",
        "Content": "<content>"
      },
      "BodyPreview": "it was great!",
      "Importance": "Normal",

       ...
    }
  ]
}

Puede ver todas las relaciones en un determinado recurso en los metadatos buscando el EntityType y observando cada NavigationProperty de ese EntityType.You can see all the relationships on a given resource by going to the metadata, finding the EntityType, and looking at each NavigationProperty for that EntityType.

Llamar a funciones y accionesCall actions and functions

Microsoft Graph también es compatible con acciones y funciones para manipular los recursos de manera que no sean simplemente operaciones de creación, lectura, actualización y eliminación (CRUD).Microsoft Graph also supports actions and functions to manipulate resources in ways that are not simply create, read, update, and delete (CRUD) operations. Suelen ser en forma de solicitudes HTTPS POST para captar los argumentos de la acción o función.They are often in the shape of HTTPS POST requests in order to intake arguments for the action or function. Por ejemplo, la siguiente acción permite al usuario que ha iniciado sesión (me) enviar un mensaje de correo electrónico.For example, the following action lets the signed-in user (me) send an email message.

POST https://graph.microsoft.com/v1.0/me/sendMail HTTP/1.1
authorization: bearer {access_token}
content-type: application/json
content-length: 96

{
  "message": {
    "subject": "Meet for lunch?",
    "body": {
      "contentType": "Text",
      "content": "The new cafeteria is open."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "garthf@contoso.onmicrosoft.com"
        }
      }
    ],
    "attachments": [
      {
        "@odata.type": "microsoft.graph.fileAttachment",
        "name": "menu.txt",
        "contentBytes": "bWFjIGFuZCBjaGVlc2UgdG9kYXk="
      }
    ]
  },
  "saveToSentItems": "false"
}

Puede ver todas las funciones que están disponibles en los metadatos. Aparecen como funciones o acciones.You can see all the functions that are available in the metadata. They appear as Functions or Actions.

Utilizar los SDK de Microsoft GraphUse the Microsoft Graph SDKs

¿Le gustan la potencia y la facilidad de los SDK? Aunque siempre puede utilizar la API de REST para llamar a Microsoft Graph, hemos proporcionado SDK para muchas plataformas populares. Para explorar las SDK que están disponibles, consulte Ejemplos de código y SDK.Like the power and ease of SDKs? While you can always use REST APIs to call Microsoft Graph, we also provide SDKs for many popular platforms. To explore the SDKs that are available, see Code samples and SDKs.

Recursos adicionalesSee also