使用 Microsoft Graph APIUse the Microsoft Graph API

Microsoft Graph 一种是可让你访问 Microsoft 云服务资源的 REST 风格的 Web API。在你注册应用获取身份验证令牌以用于用户服务后,可以向 Microsoft Graph API 发送请求。Microsoft Graph is a RESTful web API that enables you to access Microsoft Cloud service resources. After you register your app and get authentication tokens for a user or service, you can make requests to the Microsoft Graph API.

重要说明: 条件访问策略应用于 Microsoft Graph 的方式在发生变化。Important: How conditional access policies apply to Microsoft Graph is changing. 应用程序需要进行更新以处理配置了条件访问策略的应用场景。Applications need to be updated to handle scenarios where conditional access policies are configured. 有关详细信息和指南,请参阅 Azure Active Directory 条件访问开发人员指南For more information and guidance, see Developer Guidance for Azure Active Directory Conditional Access.

OData 命名空间OData namespace

Microsoft Graph API 在 Microsoft Graph 元数据的 OData 命名空间 microsoft.graph 中,定义它的大多数资源、方法和枚举。The Microsoft Graph API defines most of its resources, methods, and enumerations in the OData namespace, microsoft.graph, in the Microsoft Graph metadata. 少量的 API 集在其子命名空间中定义,例如调用记录 API 定义诸如 microsoft.graph.callRecords中的 callRecord 等资源。A small number of API sets are defined in their sub-namespaces, such as the call records API which defines resources like callRecord in microsoft.graph.callRecords.

除非在相应主题中明确指定,否则假定类型、方法和枚举是 microsoft.graph 命名空间的一部分。Unless explicitly specified in the corresponding topic, assume types, methods, and enumerations are part of the microsoft.graph namespace.

调用 REST API 方法Call a REST API method

要在资源(如用户或电子邮件)中读取或写入资源,可以创建如下请求:To read from or write to a resource such as a user or an email message, you construct a request that looks like the following:

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

请求的组成部分包括:The components of a request include:

  • {HTTP method} - 在 Microsoft Graph 请求上所使用的 HTTP 方法。{HTTP method} - The HTTP method used on the request to Microsoft Graph.
  • {version} - 你的应用程序正在使用的 Microsoft Graph API 版本。{version} - The version of the Microsoft Graph API your application is using.
  • {resource} - 你正在引用的 Microsoft Graph 中的资源。{resource} - The resource in Microsoft Graph that you're referencing.
  • {query-parameters} - 可自定义响应的可选 OData 查询选项或 REST 方法参数。{query-parameters} - Optional OData query options or REST method parameters that customize the response.

在你发出请求后,响应便会返回,其中包括:After you make a request, a response is returned that includes:

  • 状态代码 - 表示成功或失败的 HTTP 状态代码。若要详细了解 HTTP 错误代码,请参阅错误Status code - An HTTP status code that indicates success or failure. For details about HTTP error codes, see Errors.
  • 响应消息 - 请求获取的数据或操作结果。对于某些操作,响应消息可能为空。Response message - The data that you requested or the result of the operation. The response message can be empty for some operations.
  • nextLink - 如果请求返回大量数据,则需要使用 @odata.nextLink 中返回的 URL 对其进行翻页。有关详细信息,请参阅分页nextLink - If your request returns a lot of data, you need to page through it by using the URL returned in @odata.nextLink. For details, see Paging.

HTTP 方法HTTP methods

Microsoft Graph 使用请求上的 HTTP 方法来确定请求正在执行的操作。API 支持以下方法。Microsoft Graph uses the HTTP method on your request to determine what your request is doing. The API supports the following methods.

方法Method 说明Description
GETGET 从资源中读取数据。Read data from a resource.
POSTPOST 创建新的资源,或执行某个操作。Create a new resource, or perform an action.
PATCHPATCH 用新值更新资源。Update a resource with new values.
PUTPUT 替换为新资源。Replace a resource with a new one.
DELETEDELETE 删除资源。Remove a resource.
  • 对于 CRUD 方法 GETDELETE,不需要任何请求正文。For the CRUD methods GET and DELETE, no request body is required.
  • POSTPATCHPUT 方法需要通常以 JSON 格式指定的请求正文,此正文包含了其他信息,如资源的属性值。The POST, PATCH, and PUT methods require a request body, usually specified in JSON format, that contains additional information, such as the values for properties of the resource.

版本Version

Microsoft Graph 目前支持以下两种版本:v1.0betaMicrosoft Graph currently supports two versions: v1.0 and beta.

  • v1.0 包括正式可用 API。请对所有生产应用使用 v1.0 版本。v1.0 includes generally available APIs. Use the v1.0 version for all production apps.
  • beta 包括目前处于预览中的 API。因为我们可能会为试用的 API引入更大更改,我们建议你仅对开发中的测试应用使用试用版;请勿在生产应用中使用试用版 API。beta includes APIs that are currently in preview. Because we might introduce breaking changes to our beta APIs, we recommend that you use the beta version only to test apps that are in development; do not use beta APIs in your production apps.

我们一直期待用户提供 beta API 反馈。若要提供反馈或申请功能,请参阅 UserVoice 页。We are always looking for feedback on our beta APIs. To provide feedback or request features, see our UserVoice page.

若要详细了解 API 版本,请参阅版本控制和支持For more information about API versions, see Versioning and support.

ResourceResource

资源可以是实体或复杂类型,通常使用属性定义。A resource can be an entity or complex type, commonly defined with properties. 实体与复杂类型的不同之处在于前者始终包含 id 属性。Entities differ from complex types by always including an id property.

你的 URL 将包含你正在请求中与之交互的资源,如me用户驱动器网站Your URL will include the resource you are interacting with in the request, such as me, user, group, drive, and site. 通常,顶级资源还包括可以用来访问其他资源的_关系_(如 me/messagesme/drive)。Often, top-level resources also include relationships, which you can use to access additional resources, like me/messages or me/drive. 还可以使用_方法_与资源交互;例如,若要发送电子邮件,可以使用 me/sendMailYou can also interact with resources using methods; for example, to send an email, use me/sendMail. 有关详细信息,请参阅通过导航 Microsoft Graph 访问数据和方法For more information, see Access data and methods by navigating Microsoft Graph.

每个资源可能需要不同的权限来访问它。通常,你需要用来创建或更新资源的权限比读取时要求的权限更高。有关所需权限的详细信息,请参见方法引用主题。Each resource might require different permissions to access it. You will often need a higher level of permissions to create or update a resource than to read it. For details about required permissions, see the method reference topic.

有关权限的详细信息,请参阅权限引用For details about permissions, see Permissions reference.

查询参数Query parameters

查询参数可以是 OData 系统查询选项,也可以是方法接受的用于自定义其响应的其他字符串。Query parameters can be OData system query options, or other strings that a method accepts to customize its response.

你可以使用可选的 OData 系统查询选项来包含比默认响应更多或更少的属性、过滤与自定义查询匹配的项的响应,或为方法提供其他参数。You can use optional OData system query options to include more or fewer properties than the default response, filter the response for items that match a custom query, or provide additional parameters for a method.

例如,添加以下 filter 参数会将返回的邮件限制为 emailAddress 属性仅为 jon@contoso.com 的邮件。For example, adding the following filter parameter restricts the messages returned to only those with the emailAddress property of jon@contoso.com.

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

有关 OData 查询选项的详细信息,请参阅使用查询参数自定义响应For more information about OData query options, see Use query parameters to customize responses.

除 OData 查询选项之外,某些方法还需要将参数值指定为查询 URL 的一部分。Aside from OData query options, some methods require parameter values specified as part of the query URL. 例如,你可以通过查询用户calendarView 关系,并将时段 startDateTimeendDateTime 值指定为查询参数来获取用户日历中某个时间段内发生的事件的集合:For example, you can get a collection of events that occurred during a time period in a user's calendar, by querying the calendarView relationship of a user, and specifying the period startDateTime and endDateTime values as query parameters:

GET https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

用于与 Microsoft Graph 交互的工具Tools for interacting with Microsoft Graph

Graph 浏览器Graph Explorer

Graph 浏览器是一个基于 Web 的工具,可用于通过 Microsoft Graph API 构建和测试请求。Graph Explorer is a web-based tool that you can use to build and test requests using Microsoft Graph APIs. 可在以下位置访问 Graph 浏览器:https://developer.microsoft.com/graph/graph-explorerYou can access Graph Explorer at: https://developer.microsoft.com/graph/graph-explorer.

可在不登录的情况下访问演示数据,或者可登录自己的租户。You can either access demo data without signing in, or you can sign in to a tenant of your own. 请按照以下步骤生成请求:Use the following steps to build the request:

  1. 选择 HTTP 方法。Select the HTTP method.
  2. 选择要使用的 API 版本。Select the version of API that you want to use.
  3. 在请求文本框中键入查询。Type the query in the request text box.
  4. 选择“运行查询”。Select Run Query.

以下示例显示返回演示租户中的用户相关信息的请求:The following example shows a request that returns information about users in the demo tenant:

Graph 浏览器屏幕截图,突出显示 GET 用户请求

Graph 浏览器中提供了示例查询,让你能够更快地运行常见请求。Sample queries are provided in Graph Explorer to enable you to more quickly run common requests. 若要查看可用示例,请选择“显示更多示例”。To see the samples that are available, select show more samples. 对于要查看的示例集选择“打开”,然后在关闭选择窗口后,应会看到预定义的请求列表。Select On for the set of samples that you want to see, and then after closing the selection window, you should see a list of predefined requests.

发送请求后将显示状态代码和消息,并在“响应预览”选项卡中显示响应。A status code and message are displayed after a request is sent and the response is shown in the Response Preview tab.

PostmanPostman

Postman 浏览器是一款可用于使用 Microsoft Graph API 构建和测试请求的工具。Postman is a tool that you can use to build and test requests using the Microsoft Graph APIs. 可在以下位置下载 Postman:https://www.getpostman.com/You can download Postman at: https://www.getpostman.com/. 若要在 Postman 中与 Microsoft Graph 进行交互,请使用 Microsoft Graph 集合。To interact with Microsoft Graph in Postman, you use the Microsoft Graph collection.

有关详细信息,请参阅结合使用 Postman 和 Microsoft Graph APIFor more information, see Use Postman with the Microsoft Graph API.

后续步骤Next steps

你可以随时开始使用和运行 Microsoft Graph。You're ready to get up and running with Microsoft Graph. 请尝试“快速入门”或开始使用我们的其中一个 SDK 和代码示例Try the Quick Start, or get started using one of our SDKs and code samples.