使用 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 方法 GETDELETE,不需要任何请求正文。
  • POSTPATCHPUT 方法需要以 JSON 格式指定的请求正文,其中包含其他信息。 例如资源属性的值。

版本

Microsoft Graph 目前支持两个版本:v1.0beta

  • v1.0 包括已正式发布的 API。 对所有生产应用使用 v1.0 版本。
  • beta 包括目前处于预览阶段的 API。 由于我们可能对 beta API 进行重大更改,因此建议你仅使用 beta 版本测试正在开发的应用;请勿在生产应用中使用 beta API。

资源

资源可以是通常使用属性定义的实体或复杂类型。 实体与复杂类型的不同之处在于,它始终包含“id”属性。

你的 URL 中包括你要在请求中与之交互的资源,例如 me、用户、组、驱动器和站点。 通常情况下,顶级资源还包括可用于访问其他资源(如 me/messagesme/drive)的关系。 你也可以使用方法与资源进行交互;例如,要发送电子邮件,可以使用 me/sendMail

每个资源可能需要不同的权限来访问它。 创建或更新资源所需的权限通常比读取资源所需的权限更高。 有关所需权限的详细信息,请参阅方法参考主题。

查询参数

查询参数可以是 OData 系统查询选项,也可以是方法接受以自定义其响应的其他字符串。

你可以使用可选的 OData 系统查询选项来包含比默认响应更多或更少的属性。 你可以筛选响应以获取与自定义查询匹配的项,或为方法提供其他参数。

例如,添加以下 filter 参数会限制随 jon@contoso.comemailAddress 属性返回的消息。

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

其他资源

下面提供了一些工具的链接,可以使用这些工具通过 Microsoft Graph API 生成和测试请求。