通过导航 Microsoft Graph 访问数据和方法
除了使用 Microsoft 图形 API读取和写入数据外,还可以使用许多请求模式遍历 Microsoft Graph 中的资源。 元数据文档还有助于了解 Microsoft Graph 中资源和关系的数据模型。
元数据文档 ($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
}
]
}
对于 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"
}
可以查看元数据中可用的所有函数。 它们显示为“函数”或“操作”。
喜欢 SDK 的强大功能和易用性吗? 虽然你始终可以使用 REST API 来调用 Microsoft Graph,但我们也为许多常用平台提供 SDK。 若要浏览可用的 SDK,请参阅 代码示例和 SDK。