Obtener acceso a datos y métodos al navegar por 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.

Metadatos de la API de Microsoft Graph

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.

Metadatos de Microsoft Graph API v1.0

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

Metadatos beta de la API de Microsoft Graph

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.

Los metadatos también admiten la definición de tipos, los métodos y las enumeraciones en los nombres de espacios de OData correspondientes. La mayor parte de la API de Microsoft Graph se define en el nombre de espacios de OData, 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.

Nota

  • Use los Id. de recursos en el mismo caso en el que se devuelven desde las API de Microsoft Graph.
  • Suponga que los Id. de recursos, los valores que asigne y otros valores codificados en base 64 distinguen entre mayúsculas y minúsculas.
  • 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.

Ver una colección de recursos

Microsoft Graph permite ver recursos en un espacio empresarial mediante consultas HTTP GET. La respuesta a la consulta incluye las propiedades de cada recurso. Cada recurso de la entidad se identifica por su identificador. El formato de un identificador de recurso puede ser un GUID y por lo general varía según el tipo de recurso.

Por ejemplo, puede obtener la colección de recursos del user que se define en un espacio empresarial:

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.

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:

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.

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.

Continuando con el uso un usuario como ejemplo: para ver la información sobre un usuario, use una solicitud HTTPS GET para obtener un usuario específico por su identificador. Para una entidad usuario, puede usar el id. o la propiedad userPrincipalName como identificador.

En la solicitud de ejemplo siguiente se usa el valor userPrincipalName como id. del usuario.

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.

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 recurso

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:

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.

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.

Leer las propiedades específicas de los recursos de una colección

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.

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:

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:

{
  "@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ón

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.

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.

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:

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.

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.

Llamar a funciones y acciones

Microsoft Graph también es compatible acciones y con funciones para manipular los recursos de maneras que no consisten simplemente en crear, leer, actualizar y eliminar operaciones (CRUD). Suele ser en forma de solicitudes HTTPS POST para captar los argumentos de entrada para la acción o función. Por ejemplo, la siguiente acción permite al usuario que ha iniciado sesión (me) enviar un mensaje de correo electrónico.

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.

Utilizar los SDK de Microsoft Graph

¿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.

Recursos adicionales