Поделиться через

Доступ к данным и методам с помощью Microsoft Graph

  • Статья

Помимо использования microsoft API Graph для чтения и записи данных, вы можете использовать ряд шаблонов запросов для обхода ресурсов в Microsoft Graph. Документ метаданных также поможет вам понять модель данных ресурсов и связей в Microsoft Graph.

Метаданные API Microsoft Graph

Документ метаданных ($metadata) публикуется в корневом каталоге службы. Документ службы для версии 1.0 и бета-версий Microsoft API Graph можно просмотреть по следующим URL-адресам.

Метаданные API Microsoft Graph 1.0

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

Метаданные API Microsoft Graph (бета-версия)

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

Метаданные позволяют разобраться в модели данных Microsoft Graph, в том числе типах объектов, сложных типах и перечислениях, из которых состоят ресурсы, представленные в пакетах запросов и откликов.

Метаданные также поддерживают определение типов, методов и перечислений в соответствующих пространствах имен OData. Большая часть API Microsoft Graph определена в пространстве имен OData, microsoft.graph. В подпространствах имен определяется несколько API, например microsoft.graph.callRecords.

С помощью метаданных можно узнать об отношениях между объектами в Microsoft Graph и создать URL-адреса для перехода между ними.

Примечание.

  • Используйте идентификаторы ресурсов в том же регистре, в котором они возвращаются из API Microsoft Graph.
  • Считайте, что идентификаторы ресурсов, назначаемые значения и другие значения в кодировке base64 указываются с учетом регистра.
  • Считайте, что имена ресурсов URL-адреса пути, параметры запросов, имена действий и функций, их параметры текста запроса, включая названия и значения свойств API указываются без учета регистра.

Просмотр коллекции ресурсов

Microsoft Graph позволяет просматривать ресурсы в клиенте с помощью HTTP-запросов GET. Отклик на запрос включает свойства каждого ресурса. Каждый ресурс объекта определяется по соответствующему идентификатору. Формат идентификатора ресурса обычно зависит от типа ресурса.

Например, можно получить коллекцию ресурсов user, определенных в клиенте:

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

В случае успешного выполнения вы получите ответ 200 ОК, содержащий коллекцию ресурсов пользователя в полезных данных. Каждый пользователь идентифицируется свойством id и сопровождается его свойствами по умолчанию. Полезные данные, показанные ниже, усекаются для краткости.

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

      ],
      "displayName":"Alan Steiner",
      "givenName":"Alan",
      "jobTitle":"VP Corporate Marketing",
      "mail":"[email protected]",
      "mobilePhone":null,
      "officeLocation":null,
      "preferredLanguage":"en-US",
      "surname":"Steiner",
      "userPrincipalName":"[email protected]"
    }
  ]
}

Microsoft Graph также позволяет просматривать коллекции, перемещая связи одного ресурса с другим. Например, с помощью свойства навигации mailFolders пользователя можно запросить коллекцию ресурсов mailFolder в почтовом ящике пользователя:

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

В случае успешного выполнения вы получите ответ 200 OK, содержащий коллекцию ресурсов mailFolder в полезных данных. Каждый mailFolder идентифицируется свойством id и сопровождается его свойствами. Полезные данные, показанные ниже, усекаются для краткости.

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
    }
  ]
}

Просмотр ресурса из коллекции по идентификатору

Для большинства сущностей в Microsoft Graph идентификатор является первичным ключом.

Еще раз приведем ресурс user в качестве примера. Чтобы просмотреть сведения об определенном пользователе, отправьте HTTPS-запрос GET, указав идентификатор объекта user. Для объекта user в качестве идентификатора можно использовать свойство id или userPrincipalName.

В следующем примере запроса в качестве идентификатора используется значение userPrincipalName.

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

При успешном выполнении запроса будет получен отклик 200 OK, содержащий полезные данные с представлением ресурса user, как показано ниже.

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": "[email protected]",

    ...
}

Просмотр определенного ресурса из коллекции по альтернативному ключу

Некоторые сущности поддерживают альтернативный ключ, который можно использовать для получения объекта вместо идентификатора первичного ключа. Например, сущности application и servicePrincipal поддерживают альтернативный ключ appId .

В следующем примере используется синтаксис альтернативного ключа для получения субъекта-службы по его идентификатору appId.

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

Чтение определенных свойств ресурса

Чтобы получить только биографические данные пользователя, например предоставленное им описание в разделе Обо мне и набор квалификационных навыков, в предыдущий запрос можно добавить параметр $select, как показано в следующем примере.

GET https://graph.microsoft.com/v1.0/users/[email protected]?$select=displayName,aboutMe,skills HTTP/1.1
Authorization : Bearer {access_token}

При успешном выполнении запроса в отклике возвращаются полезные данные и состояние 200 OK, как показано ниже.

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"
    ]
}

Здесь возвращаются не полные наборы свойств для объекта user, а только основные свойства aboutMe, displayName и skills.

При выполнении запроса GET без использования $select для ограничения объема данных свойств Microsoft Graph включает свойство @microsoft.graph.tips , которое предоставляет рекомендации по использованию $select , аналогичное следующему сообщению:

"@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",

Чтение только одного свойства ресурса

Вы можете получить одно свойство ресурса без использования $select, указав имя свойства в качестве сегмента пути. Этот запрос не позволяет получить несколько свойств, но он может быть полезен, если требуется только одно свойство.

В следующем примере извлекается displayName пользователя.

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

Чтение отдельных свойств ресурсов в коллекции

Вы можете не только просматривать отдельные свойства одного ресурса, но и получить все ее ресурсы только с указанными свойствами, применив к коллекции аналогичный параметр запроса $select.

Например, чтобы запросить имена элементов на диске вошедшего пользователя, можно отправить следующий HTTPS-запрос GET.

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

При успешном ответе возвращаются код состояния 200 OK и полезные данные, содержащие только имена общих файлов, как показано в следующем примере.

{
  "@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"
    }
  ]
}

Переход от одного ресурса к другому с помощью отношения

Руководитель имеет отношения directReports с другими пользователями, сообщая ему или ей. Чтобы запросить список подчиненных пользователя, можно использовать приведенный ниже HTTPS-запрос GET для перехода к целевому объекту с помощью отношения.

GET https://graph.microsoft.com/v1.0/users/[email protected]/directReports HTTP/1.1
Authorization : Bearer {access_token}

При успешном выполнении запроса в отклике возвращаются полезные данные и состояние 200 OK, как показано ниже.

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

    ...
}

Аналогичным образом вы можете воспользоваться отношением, чтобы перейти к связанным ресурсам. Например, связь "пользователь—сообщения" позволяет переходить от Microsoft Entra пользователя к набору почтовых сообщений Outlook. В следующем примере показано, как это сделать в вызове REST API.

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

При успешном выполнении запроса в отклике возвращаются полезные данные и состояние 200 OK, как показано ниже.

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

       ...
    }
  ]
}

Чтобы просмотреть все отношения для ресурса, откройте метаданные, найдите параметр EntityType и просмотрите все его свойства NavigationProperty.

Вызов действий и функций

Microsoft Graph также поддерживает действия и функции для выполнения с ресурсами действий, отличных от простых операций CRUD (создание, чтение, обновление и удаление). Они часто имеют форму HTTPS-запросов POST, принимающих аргументы для действия или функции. Например, с помощью указанного ниже действия вошедший пользователь (me) может отправить сообщение электронной почты.

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": "[email protected]"
        }
      }
    ],
    "attachments": [
      {
        "@odata.type": "microsoft.graph.fileAttachment",
        "name": "menu.txt",
        "contentBytes": "bWFjIGFuZCBjaGVlc2UgdG9kYXk="
      }
    ]
  },
  "saveToSentItems": "false"
}

Вы можете просмотреть все функции, доступные в метаданных. Они отображаются как Функции или Действия.

Использование пакетов SDK Microsoft Graph

Вам нравятся возможности и удобство пакетов SDK? Хотя вы всегда можете использовать REST API для вызова Microsoft Graph, мы также предоставляем пакеты SDK для многих популярных платформ. Чтобы изучить доступные пакеты SDK, см. статью Примеры кода и пакеты SDK.

Связанные материалы