Obtener acceso a datos y métodos al navegar por Microsoft Graph

  • Artículo

Además de usar microsoft Graph API para leer y escribir datos, puede usar una serie de patrones de solicitud para recorrer los recursos de Microsoft Graph. El documento de metadatos también le ayuda a comprender el modelo de datos de los recursos y las relaciones de 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 de las versiones v1.0 y beta de Microsoft Graph API a través de las siguientes direcciones 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. Algunas API se definen en subnombres, por ejemplo, microsoft.graph.callRecords.

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 de la consulta incluye las propiedades de cada recurso. Cada uno de los recursos de la entidad se identifica por su ID. Por lo general, el formato de un identificador de recurso 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 se ejecuta correctamente, obtendrá una respuesta 200 OK que contiene la colección de recursos de usuario de la carga. Cada usuario se identifica mediante la propiedad id y se acompaña de sus propiedades predeterminadas. La carga que se muestra a continuación se trunca por brevedad.

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.com",
      "mobilePhone":"+1 3528700812",
      "officeLocation":null,
      "preferredLanguage":"en-US",
      "surname":"Administrator",
      "userPrincipalName":"admin@contoso.com"
    },
    {
      "id":"d66f2902-9d12-4ff8-ab01-21ec6706079f",
      "businessPhones":[

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

Microsoft Graph también permite ver colecciones navegando por las relaciones de un recurso con otro. Por ejemplo, a través de la propiedad de navegación mailFolders de un usuario, puede consultar la colección de recursos mailFolder en el buzón del usuario:

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

Si se ejecuta correctamente, obtendrá una respuesta 200 OK que contiene la colección de recursos mailFolder en la carga. Cada mailFolder se identifica mediante la propiedad id y se acompaña de sus propiedades. La carga que se muestra a continuación se trunca por brevedad.

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.

Para la mayoría de las entidades de Microsoft Graph, el identificador es la clave principal.

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. Para una entidad user, puede usar como identificador la propiedad id o la propiedad userPrincipalName.

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.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.com",

    ...
}

Visualización de un recurso específico de una colección mediante una clave alternativa

Algunas entidades admiten una clave alternativa, que puede usar para recuperar un objeto en lugar del identificador de clave principal. Por ejemplo, las entidades application y servicePrincipal admiten la clave alternativa appId .

En el ejemplo siguiente se usa la sintaxis de clave alternativa para recuperar una entidad de servicio mediante su appId.

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='00000003-0000-0000-c000-000000000000') HTTP/1.1
Authorization : Bearer {access_token}

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

Al realizar una solicitud GET sin usar $select para limitar la cantidad de datos de propiedades, Microsoft Graph incluye una propiedad @microsoft.graph.tips que proporciona una recomendación de procedimientos recomendados para usar $select de forma similar al siguiente mensaje:

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

Leer solo una propiedad de un recurso

Puede recuperar una sola propiedad de un recurso sin usar $select, especificando el nombre de propiedad como un segmento de ruta de acceso. Esta consulta no le permite recuperar varias propiedades, pero puede ser útil cuando solo necesita una sola propiedad.

En el ejemplo siguiente se recupera el displayName de un usuario.

GET https://graph.microsoft.com/beta/users/8afc02cb-4d62-4dba-b536-9f6d73e9be26/displayName HTTP/1.1
Authorization : Bearer {access_token}

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.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 los demás usuarios que le informan. 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.com/directReports 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: 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 el recorrido de un usuario Microsoft Entra a un conjunto de mensajes de correo de Outlook. En el ejemplo siguiente se muestra cómo hacerlo en una llamada a la API 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.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 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). Suelen ser en forma de solicitudes HTTPS POST para captar los argumentos de 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.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 usar las API rest para llamar a Microsoft Graph, también proporcionamos SDK para muchas plataformas populares. Para explorar los SDK que están disponibles, consulte Ejemplos de código y SDK.

Contenido relacionado