使用 REST 查询 Microsoft Graph
Microsoft Graph 是一种 RESTful Web API,可用于访问 Microsoft 云服务资源。 注册应用并获取用户或服务的身份验证令牌后,可以向 Microsoft Graph API 发出请求。
Microsoft Graph API 在 Microsoft Graph 元数据的 OData 命名空间 microsoft.graph
中定义大部分资源、方法和枚举。 一些 API 集是在其子命名空间中定义的,例如用于定义资源(如 microsoft.graph.callRecords
中的 callRecord)的 call records API。
除非在相应主题中显式指定,否则假定类型、方法和枚举是 microsoft.graph
命名空间的一部分。
调用 REST API 方法
要读取或写入资源(例如用户或电子邮件),请构造如下所示的请求:
{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}
请求的各个部分如下:
{HTTP method}
- 对 Microsoft Graph 的请求所用的 HTTP 方法。{version}
- 应用程序正在使用的 Microsoft Graph API 的版本。{resource}
- 正在引用的 Microsoft Graph 中的资源。{query-parameters}
- 用于自定义响应的可选 OData 查询选项或 REST 方法参数。
当你发出请求后,将返回响应,其中包括:
- 状态代码 - 指示成功或失败的 HTTP 状态代码。
- 响应消息 - 你请求的数据或操作的结果。 对于某些操作,响应消息可能是空的。
nextLink
- 如果你请求返回大量数据,需要使用@odata.nextLink
中返回的 URL 来浏览这些数据。
HTTP 方法
Microsoft Graph 对你的请求使用 HTTP 方法来确定你的请求是什么。 API 支持以下方法。
方法 | 说明 |
---|---|
GET | 从资源中读取数据。 |
POST | 创建新资源或执行操作。 |
修补程序 | 使用新值更新资源。 |
PUT | 使用新资源替换资源。 |
DELETE | 删除资源。 |
- 对于 CRUD 方法
GET
和DELETE
,不需要任何请求正文。 POST
、PATCH
和PUT
方法需要以 JSON 格式指定的请求正文,其中包含其他信息。 例如资源属性的值。
版本
Microsoft Graph 目前支持两个版本:v1.0
和 beta
。
v1.0
包括已正式发布的 API。 对所有生产应用使用 v1.0 版本。beta
包括目前处于预览阶段的 API。 由于我们可能对 beta API 进行重大更改,因此建议你仅使用 beta 版本测试正在开发的应用;请勿在生产应用中使用 beta API。
资源
资源可以是通常使用属性定义的实体或复杂类型。 实体与复杂类型的不同之处在于,它始终包含“id”属性。
你的 URL 中包括你要在请求中与之交互的资源,例如 me
、用户、组、驱动器和站点。 通常情况下,顶级资源还包括可用于访问其他资源(如 me/messages
或 me/drive
)的关系。 你也可以使用方法与资源进行交互;例如,要发送电子邮件,可以使用 me/sendMail
。
每个资源可能需要不同的权限来访问它。 创建或更新资源所需的权限通常比读取资源所需的权限更高。 有关所需权限的详细信息,请参阅方法参考主题。
查询参数
查询参数可以是 OData 系统查询选项,也可以是方法接受以自定义其响应的其他字符串。
你可以使用可选的 OData 系统查询选项来包含比默认响应更多或更少的属性。 你可以筛选响应以获取与自定义查询匹配的项,或为方法提供其他参数。
例如,添加以下 filter
参数会限制随 jon@contoso.com
的 emailAddress
属性返回的消息。
GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'
其他资源
下面提供了一些工具的链接,可以使用这些工具通过 Microsoft Graph API 生成和测试请求。