Azure AD Graph と Microsoft Graph の違いを要求する
この記事は、アプリを移行するプロセスの API の違いを確認する手順 1 の一部です。
Microsoft Graph と Azure Active Directory (Azure AD) Graph APIは、どちらもクエリ パラメーターの OData 規則をサポートする REST API です。 ただし、構文はこれら 2 つの API によって異なります。
Graph エクスプローラーを使用して、独自のデータに対してこれらの要求パターンを試し、コードを更新する前に要求と応答の違いについて学習します。
基本的な要求
次の表は、2 つの API のメイン要求の違いを示しています。
| リクエストの詳細 | Azure AD Graph | Microsoft Graph |
|---|---|---|
| 要求構文 | https://graph.windows.net/{tenant_id}/{resource}?{version}&query-parameters |
https://graph.microsoft.com/{version}/{resource}?query-parameters |
| サービス エンドポイント: | ||
| -グローバル | https://graph.windows.net |
https://graph.microsoft.com |
| - US Gov L4 | https://graph.microsoftazure.us |
https://graph.microsoft.us |
| - US Gov L5 (DOD) | https://graph.microsoftazure.us |
https://dod-graph.microsoft.us |
| - ドイツ (廃止) | https://graph.cloudapi.de |
https://graph.microsoft.de |
| - 中国 (21Vianet) | https://graph.chinacloudapi.cn |
https://microsoftgraph.chinacloudapi.cn |
| {tenant_id} | 要求でテナント ID またはドメイン名を指定します。 | 省略可能です。 テナント ID は、アクセス トークンから推論されます。 テナント ID を指定する場合は、次の構文を使用します。 https://graph.microsoft.com/{version}/{tenant_id}/{resource}?query-parameters |
| {version} | 必要なクエリ パラメーターを使用して、要求で Azure AD Graph のリリース バージョンを指定します。 | サービス エンドポイントの直後の URL パスの一部として、要求で Microsoft Graph のリリース バージョンを指定します。 |
クエリ パラメーターの構文は、Microsoft Graph と Azure AD Graph で同じです。 ただし、Microsoft Graph では、Azure AD Graph よりも多くのクエリ パラメーターとクエリ機能がサポートされています。
要求の比較の例
Contoso テナントで "Dan" で始まる名前を持つすべてのユーザーの一覧が必要だとします。 次の表は、Azure AD Graph と Microsoft Graph の要求の違いを示しています。
| Azure AD Graph | Microsoft Graph |
|---|---|
GET https://graph.windows.net/contoso.com/users?$filter=startswith(givenName,'Dan')&api-version=1.6 |
GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName,'Dan') |
主キー識別子: objectId と id
Azure AD Graph では、すべてのエンティティ リソースの種類に objectId という一意の識別子 (または主キー) があります。 ほとんどのエンティティ (特に明記されていない限り) では、この識別子は Microsoft Graph で id と呼ばれます。
主キーに加えて、一部のエンティティでは代替キー識別子がサポートされています。 たとえば、Microsoft Graph の application リソースと servicePrincipal リソースでは、 appId プロパティの代替キー識別子がサポートされています。
既定のプロパティと$select
アプリで実際に必要なプロパティのみを要求することをお勧めします。 GET 要求でクエリ パラメーターを $select 使用して、アプリに必要なプロパティのみを含むように応答をカスタマイズします。
Microsoft Graph では、ユーザーリソースやグループ リソースの GET 操作や LIST 操作など、すべてのプロパティのサブセットのみが返される場合があります。 これらの 既定のプロパティ は、リソースで最もよく使用されるプロパティを表します。 一方、Azure AD Graph は、それぞれのリソースのすべてのプロパティの完全なセットを返します。 リソースが既定のプロパティのみを返す場合、アプリはクエリ パラメーターを使用して他のプロパティを明示的に要求する $select 必要があります。
違いを説明するには、Graph エクスプローラー を使用して次の要求を実行し、さまざまな応答を比較します。
GET https://graph.microsoft.com/v1.0/me/
GET https://graph.microsoft.com/beta/me/
応答の違いに注目してください。 バージョンは /beta 、バージョンよりも多くのプロパティを /v1.0 返します。 たとえば、アプリが streetAddress プロパティに依存している場合は、クエリ パラメーターを v1.0 使用 $select して、アプリに必要なその他のプロパティに加えて streetAddress プロパティを要求するように要求を更新する必要があります。 以下に例を示します。
https://graph.microsoft.com/v1.0/me?$select=displayName,streetAddress,city,state,postalCode
詳細については、以下を参照してください。
- ユーザー リソースとグループ リソースの既定のプロパティについては、「ユーザーとグループ」を参照してください
- パラメーターとその他のサポートされている ODATA クエリ パラメーターについては
$select、「 クエリ パラメーターを使用して応答をカスタマイズする」を参照してください。 - その他の推奨される最適化については、「 ベスト プラクティス」を参照してください。
リレーションシップとナビゲーション プロパティ
リレーションシップ (またはナビゲーション プロパティ) は、Azure AD Graph と Microsoft Graph の重要な概念であり、関連リソースのネットワークを作成します。 たとえば、 マネージャー プロパティと directReports プロパティは 、組織の階層を提供するためにユーザー リソースを拡張します。
リレーションシップは、ユーザーが属するグループ、グループまたはディレクトリ ロールに属するメンバーなどのメンバーシップも定義します。
Azure AD Graph 要求は、リソース間のリレーションシップを示すために使用 $links します。 Microsoft Graph では、代わりに OData v4.01 $ref 表記が使用されます。
次の表に、いくつかの例を示します。
| タスク | Azure AD Graph | Microsoft Graph |
|---|---|---|
| メンバーを追加する | POST /groups/{id}/$links/members |
POST /groups/{id}/members/$ref |
| メンバー リンクを一覧表示する | GET /groups/{id}/$links/members |
GET /groups/{id}/members/$ref |
| メンバーを一覧表示する | GET /groups/{id}/members |
GET /groups/{id}/members |
| メンバーを削除する | DELETE /groups/{id}/$links/members/{id} |
DELETE /groups/{id}/members/{id}/$ref |
アプリを Microsoft Graph に移行する場合は、代わりに使用するリソースを関連付けるために使用$links$refする参照を更新します。