通过导航 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 的格式通常因资源类型而异。
例如，可以获取在租户中定义的用户资源集合：
如果成功，你将得到一个 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 资源集合。 每个 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
}
]
}
按 ID 查看集合中的特定资源
对于 Microsoft Graph 中的大多数实体， ID 是主键。
继续使用用户作为示例 - 要查看有关用户的信息，则使用 HTTP GET 请求根据用户 ID 获取特定用户。 对于用户实体，可以使用 id 或 userPrincipalName 属性作为标识符。
以下请求示例使用 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"
]
}
此时，仅返回 aboutMe、displayName 和 skills 基本属性（而不是 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。
相关内容
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈