通过导航 Microsoft Graph 访问数据和方法

除了使用 Microsoft 图形 API读取和写入数据外,还可以使用许多请求模式遍历 Microsoft Graph 中的资源。 元数据文档还有助于了解 Microsoft Graph 中资源和关系的数据模型。

Microsoft Graph API 元数据

元数据文档 ($metadata) 在服务根处发布。 可以通过以下 URL 查看 Microsoft 图形 API v1.0 和 beta 版本的服务文档。

Microsoft Graph API v1.0 元数据

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

Microsoft Graph API beta 元数据

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

元数据允许你查看并了解 Microsoft Graph 数据模型,包括实体类型、复杂类型、组成在请求和响应数据包中表示的资源的枚举。

元数据还支持在相应的 OData 命名空间中定义类型、方法和枚举。 大多数 Microsoft Graph API 在 OData 命名空间 microsoft.graph 中定义。 子空间中定义了一些 API,例如 microsoft.graph.callRecords

可以使用元数据了解 Microsoft Graph 中实体之间的关系,并建立可在这些实体间导航的 URL。

注意

  • 在使用资源 ID 时,应保持与其从 Microsoft Graph API 返回时相同的大小写。
  • 假设资源 ID、分配的值和其他 base-64 编码的值区分大小写
  • 假设路径 URL 资源名称、查询参数、操作、函数名称及其请求正文参数(包括任何 API 属性名称和值)均不区分大小写

查看资源集合

Microsoft Graph 允许用户使用 HTTP GET 查询来查看租户中的资源。 查询响应包括每个资源的属性。 实体资源均由其 ID 标识。 资源 ID 的格式通常因资源类型而异。

例如,可以获取在租户中定义的用户资源集合:

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

如果成功,你将得到一个 200 OK 响应,其中包含有效负载中的 用户 资源集合。 每个用户由 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":"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 还允许你通过导航一个资源与另一个资源的关系来查看集合。 例如,通过用户的 mailFolders 导航属性,可以在用户的邮箱中查询 mailFolder 资源的集合:

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

如果成功,你将得到一个 200 OK 响应,其中包含有效负载中的 mailFolder 资源集合。 每个 mailFolderid 属性标识,并附带其属性。 为简洁起见,下面所示的有效负载被截断。

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

按 ID 查看集合中的特定资源

对于 Microsoft Graph 中的大多数实体, ID 是主键。

继续使用用户作为示例 - 要查看有关用户的信息,则使用 HTTP GET 请求根据用户 ID 获取特定用户。 对于用户实体,可以使用 iduserPrincipalName 属性作为标识符。

以下请求示例使用 userPrincipalName 值作为用户 ID。

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

如果成功,便会收到“200 正常”响应,其中包含有效负载中的用户资源表示,如下所示。

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

    ...
}

按备用键查看集合中的特定资源

某些实体支持备用键,可用于检索对象而不是主键 ID。 例如, 应用程序 实体和 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/john.doe@contoso.com?$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"
    ]
}

此时,仅返回 aboutMedisplayNameskills 基本属性(而不是 user 实体上的整个属性集)。

在不使用 来限制属性数据量的情况下 $select 发出 GET 请求时,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/john.doe@contoso.com/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 正常”状态和有效负载,如下所示。

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,并查看该 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": "garthf@contoso.com"
        }
      }
    ],
    "attachments": [
      {
        "@odata.type": "microsoft.graph.fileAttachment",
        "name": "menu.txt",
        "contentBytes": "bWFjIGFuZCBjaGVlc2UgdG9kYXk="
      }
    ]
  },
  "saveToSentItems": "false"
}

可以查看元数据中可用的所有函数。 它们显示为“函数”或“操作”。

使用 Microsoft Graph SDK

喜欢 SDK 的强大功能和易用性吗? 虽然你始终可以使用 REST API 来调用 Microsoft Graph,但我们也为许多常用平台提供 SDK。 若要浏览可用的 SDK,请参阅 代码示例和 SDK