请求 Azure AD Graph 和 Microsoft Graph 之间的差异Request differences between Azure AD Graph and Microsoft Graph

本文是第1步:查看迁移应用程序的 API 差异的过程的一部分。This article is part of step 1: review API differences of the process to migrate apps.

Microsoft Graph 和 Azure AD Graph API 都是 REST Api,它们分别支持查询参数的 ODATA 约定。Microsoft Graph and the Azure AD Graph API are both REST APIs and they each support ODATA conventions for query parameters. 但是,这两个 Api 的语法各不相同。However, the syntax varies between these two APIs.

使用 Graph 浏览器 针对您自己的数据尝试这些请求模式,因为这是了解请求和响应差异的一种很好的方法。Use the Graph Explorer to try these request patterns against your own data, as it's a great way to learn about the request and response differences.

基本请求Basic requests

下表突出显示了这两个 Api 之间的主要请求差异:The following table highlights the main request differences between the two APIs:

请求详细信息Request details Azure AD GraphAzure AD Graph Microsoft GraphMicrosoft Graph
请求语法Request syntax https://graph.windows.net/{tenant_id}/
{resource}?{version}&query-parameters
https://graph.microsoft.com/
{version}/{resource}?query-parameters
服务   终结点:Service endpoints:
- 全局性- Global https://graph.windows.net https://graph.microsoft.com
- US   .Gov   L4- US Gov L4 https://graph.microsoftazure.us https://graph.microsoft.us
- 美国   .Gov   L5   (DOD) - US Gov L5 (DOD) https://graph.microsoftazure.us https://dod-graph.microsoft.us
- 德国- Germany https://graph.cloudapi.de https://graph.microsoft.de
- 中国   (世纪) - China (21Vianet) https://graph.chinacloudapi.cn https://microsoftgraph.chinacloudapi.cn
{tenant_id}{tenant_id} 指定请求中租户的 ID。Specify the ID of the tenant in the request. 在请求中指定的租户 ID 是可从访问令牌推断出的可选方法。It's optional to specify a tenant ID in the request as it is inferred from the access token.

如果您指定租户 ID,它将在 {version} {resource} 请求 URL 中的和之间。If you specify the tenant ID, it goes between the {version} and the {resource} in the request URL.
版本{version} 使用所需的查询参数在请求中指定 Azure AD Graph 的发布版本。Specify the release version of Azure AD Graph in the request using a required query parameter. 在请求中将 Microsoft Graph 的发布版本指定为服务终结点之后的 URL 路径的一部分。Specify the release version of Microsoft Graph in the request as part of the URL path just after the service endpoint.

您可以继续在 Microsoft Graph 中使用与 Azure AD Graph 相同的查询参数。You can continue to use the same query parameters in Microsoft Graph as Azure AD Graph.

示例请求比较Example request comparison

假设您需要一个名称以 "Dan" 开头的所有用户的列表。Suppose you want a list of all users with names beginning with "Dan".

在 Azure AD Graph 中,可以使用此请求:In Azure AD Graph, you might use this request:

GET https://graph.windows.net/contoso.com/users?$filter=startswith(givenName,'Dan')&api-version=1.6GET https://graph.windows.net/contoso.com/users?$filter=startswith(givenName,'Dan')&api-version=1.6 or

GET https://graph.windows.net/myOrganization/users?$filter=startswith(givenName,'Dan')&api-version=1.6

此请求:This request:

  • 面向 Azure AD Graph 的版本1.6。Targets version 1.6 of Azure AD Graph.
  • 指定 contoso.com 为租户 ID。Specifies contoso.com as the tenant ID. 替代方法显示了如何 myOrganization 根据访问令牌中的租户 ID 使用别名。The alternative shows the use of an alias myOrganization based on the tenant ID in the access token.
  • 调用用户资源。Calls the users resource.
  • 使用 $filter 查询参数将响应限制为以开头的给定名称 DanUses the $filter query parameter to limit the response to given names that begin with Dan.

结果包括名称如 Daniel、Danforth、Danielle、Danerys 等的用户。Results include users with names like Daniel, Danforth, Danielle, Danerys, and so on.

Microsoft Graph 的类似请求如下:A similar request for Microsoft Graph would be:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName,'Dan')

如下Here:

  • 版本为 v1.0The version is v1.0.
  • 租户 ID 是从访问令牌中推断出来 (不会) 显示。The tenant ID is inferred from the access token (not shown).
  • 资源和 $filter 查询参数与 AZURE AD 查询相同。The resource and $filter query parameter are the same as the Azure AD query.

注意:如果使用的是 Azure AD Graph .net 客户端库,请参阅 .net 客户端库 ,了解更多特定策略和帮助,以移动到 Microsoft Graph .net 客户端库。NOTE: If you're using the Azure AD Graph .NET client library, see .NET client libraries for more specific strategies and assistance to move to the Microsoft Graph .NET client library.

键标识符: objectId vs idKey identifiers: objectId vs id

在 Azure AD Graph 中,所有实体资源类型都有一个唯一的标识符 (或称为 objectId的键) 。In Azure AD Graph, all entity resource types have a unique identifier (or key) called objectId. 大多数情况 ((除非另有说明)) 此同一标识符在 Microsoft Graph 中称为 idFor the most part (unless otherwise stated) this same identifier is called id in Microsoft Graph.

默认属性和 $selectDefault properties and $select

使用 $select GET requests 中的查询参数自定义响应,以包含您的应用程序所需的所有属性。Use the $select query parameter, in GET requests, to customize the response to include all the properties that your app requires.

Microsoft Graph getlist 操作对于用户或组资源,仅返回所有属性(称为 默认属性)的子集。Microsoft Graph get or list operations for user or group resources returns only a subset of all properties, known as the default properties. 默认属性表示资源的最常用属性。The default properties represent the most commonly-used properties for a resource. 另一方面,Azure AD Graph 将返回相应资源的所有属性的完整集。On the other hand, Azure AD Graph returns the full set of all properties for the respective resource.

若要获取 v1.0 中的其他属性,应用需要使用查询参数显式请求这些属性 $selectTo get other properties in v1.0, your app needs to explicitly request them, using the $select query parameter. 这包括您的应用程序可能使用的任何目录架构扩展。This includes any directory schema extensions your app might be using. 最佳做法是仅请求应用程序真正需要的属性。It's a best practice to only request the properties your app really needs.

为了说明区别,请使用 Graph 浏览器运行以下请求并比较不同的响应。To illustrate the difference, use Graph Explorer to run the following requests and compare the different responses.

GET https://graph.microsoft.com/v1.0/me/
GET https://graph.microsoft.com/beta/me/

查看每个查询的响应。Review the responses from each query. 您会注意到,地址信息是由/beta 版本(而不是/v1.0 版本)返回的。You'll notice that address information is returned by the /beta version, but not the /v1.0 version. 这是因为地址属性不在默认属性集中。That's because the address properties aren't in the default property set.

如果您的应用程序依赖于地址属性,则需要更新您的 v1.0 请求以包含 $select 查询参数:If your app relies on the address properties, you need to update your v1.0 requests to include the $select query parameter:

https://graph.microsoft.com/v1.0/me/?$select=displayName,streetAddress,city,state,postalCode

此请求的响应将包括地址属性。The response for this request would include the address properties. 它还包括 displayName 属性,但仅由于它是由查询参数指定的。It also includes the displayName property, but only because it was specified by the query parameter.

若要了解详细信息,请参阅:To learn more about:

关系和导航属性Relationships and navigation properties

关系 (或导航属性) 是 Azure AD Graph 和 Microsoft Graph 中的关键概念,创建了相关资源的网络。Relationships (or navigation properties) are a key concept in Azure AD Graph and Microsoft Graph, creating a network of related resources. 例如, managerdirectReports 属性扩展了用户资源,以提供组织的层次结构。For example, the manager and directReports properties extend the user resource to provide organizational hierarchy.

关系还定义成员身份,如用户所属的组、属于某个组的成员或目录角色,等等。Relationships also define memberships, such as the groups a user belongs to, the members belonging to a group or a directory role, and so on.

Azure AD Graph 请求用于 $link 指示资源之间的关系。Azure AD Graph requests use $link to indicate relationships between resources. 在 Microsoft Graph 中,使用的是 ODATA 4.01 $ref 表示法。In Microsoft Graph this uses the ODATA 4.01 $ref notation instead.

下表显示了几个示例:The following table shows several examples:

任务Task Azure AD GraphAzure AD Graph Microsoft GraphMicrosoft Graph
添加成员Add member POST /groups/{id}/$link/members POST /groups/{id}/members/$ref
列出成员链接List member links GET /groups/{id}/$link/members GET /groups/{id}/members/$ref
列出成员List members GET /groups/{id}/members GET /groups/{id}/members
删除成员Remove member DELETE /groups/{id}/$link/members/{id} DELETE /groups/{id}/members/{id}/$ref

将应用程序迁移到 Microsoft Graph 时,请查找使用 $link 关联资源的请求; 请将这些请求更改为改用 $refWhen migrating your apps to Microsoft Graph, look for requests that use $link to associate resources; change these to use $ref instead.

后续步骤Next Steps