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. ただし、この2つの Api の構文は異なります。However, the syntax varies between these two APIs.

グラフエクスプローラーを使用して、要求と応答の違いについて理解するための最適な方法として、自分のデータに対してこれらの要求パターンを試してみてください。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

次の表は、2つの 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
- 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
- 中国   (21vianet)- 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.
4.0{version} 必要なクエリパラメーターを使用して、要求に Azure AD Graph のリリースバージョンを指定します。Specify the release version of Azure AD Graph in the request using a required query parameter. 要求では、サービスエンドポイントの直後の URL パスの一部として、Microsoft Graph のリリースバージョンを指定します。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. これは、アクセストークンのテナント ID に基づくエイリアスの使用方法を示して myOrganization います。The alternative shows the use of an alias myOrganization based on the tenant ID in the access token.
  • ユーザーリソースを呼び出します。Calls the users resource.
  • は、クエリパラメーターを使用して $filter 、指定された名前ので始まる応答を制限し Dan ます。Uses 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.0 です。The version is v1.0.
  • テナント ID は、アクセストークンから推論されます (ここでは示されていません)。The tenant ID is inferred from the access token (not shown).
  • Resource パラメーターと $filter query パラメーターは 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 では id と呼ばれます。For the most part (unless otherwise stated) this same identifier is called id in Microsoft Graph.

既定のプロパティと $selectDefault properties and $select

$selectGET 要求でクエリパラメーターを使用して、アプリが必要とするすべてのプロパティを含むように応答をカスタマイズします。Use the $select query parameter, in GET requests, to customize the response to include all the properties that your app requires.

Microsoft Graph の get または list 操作ユーザーまたはグループのリソースは、すべてのプロパティのサブセットを返します ( _既定のプロパティ_と呼ばれます)。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.

V 1.0 のその他のプロパティを取得するには、クエリパラメーターを使用して、アプリで明示的に要求する必要があり $select ます。To 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. アドレス情報は、ベータ版では返されますが、/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.

アプリがアドレスプロパティに依存している場合は、次のように、version 1.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. たとえば、 マネージャー および directreports プロパティは、ユーザーリソースを拡張して組織階層を提供します。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 ます。代わりに、代わりにを使用するように変更 $ref してください。When migrating your apps to Microsoft Graph, look for requests that use $link to associate resources; change these to use $ref instead.

次の手順Next Steps