操作の概要 | Graph API の概念
Azure Active Directory (AD) Graph API は、テナントのユーザー、グループ、連絡先などのオブジェクトの読み取りや変更に使用できる OData 3.0 準拠のサービスです。 Azure AD Graph API は、このサービスを使用する操作を実行するために、HTTP 要求の送信先である REST エンドポイントを公開しています。 次のセクションでは、要求の書式設定、および Graph API を使用したディレクトリ リソースの読み書き、ディレクトリの関数またはアクションの呼び出し、ディレクトリに対するクエリの実行で期待される応答に関する一般的な情報を提供します。 特定の操作のディレクトリ リソースの実行の詳細については、「Azure AD Graph API リファレンス」の該当するトピックを参照してください。
Graph API への要求が成功した場合、有効なエンドポイントにアドレス指定され、適切な書式が設定されています。つまり、要求本文に必要なヘッダーと、場合によっては JSON ペイロードが含まれています。 要求を行うアプリには、要求の対象となるリソースにアクセスする権限があることを証明する Azure AD から受信したトークンを含める必要があります。 アプリは、Graph API から受信したすべての応答を処理できる必要があります。
このトピックのセクションは、要求の書式および Graph API で使用される応答を理解するのに役立ちます。
重要
Azure Active Directory のリソースにアクセスするには、Azure AD Graph API ではなく Microsoft Graph を使用することを強くお勧めします。現在は Microsoft Graph を中心にして開発が進められており、Azure AD Graph API の今後の機能強化は予定されていません。Azure AD Graph API の使用が適切である場合もありますが、非常にまれです。詳細については、Office Dev Center の Microsoft Graph または Azure AD Graph ブログの記事をご覧ください。
認証と承認
Graph API に対するすべての要求には、アタッチされている Azure Active Directory によって発行されるベアラー トークンが必要です。 このトークンには、アプリ、サインインしたユーザー (委任された権限の場合)、認証、アプリで実行が許可されているディレクトリに対する操作に関する情報が含まれています。 このトークンは、要求の Authorization ヘッダーで運ばれます。 例 (簡略化のため、トークンは短縮しています):
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Graph API が、トークンにある OAuth 2.0 アクセス許可スコープに基づいて承認を実行します。 Graph API が公開するアクセス許可スコープの詳細については、「Graph API Permission Scopes (Graph API のアクセス許可スコープ)」を参照してください。
アプリを Azure AD で認証し、Graph API を呼び出せるようにするには、アプリをテナントに追加し、Microsoft Azure Active Directory のアクセス許可 (OAuth 2.0 アクセス許可スコープ) を必要とするように構成する必要があります。 アプリの追加および構成については、「Azure Active Directory とアプリケーションの統合」を参照してください。
Azure AD は OAuth 2.0 認証プロトコルを使用します。 サポートされているフローとアクセス トークンを含む、Azure AD の OAuth 2.0 の詳細については、「Azure AD での OAuth 2.0」を参照してください。
エンドポイントのアドレス指定
Graph API を使用して操作を実行するには、サポートされているメソッド (GET、POST、PATCH、PUT、または DELETE) を指定した HTTP 要求を、サービス、リソース コレクション、個々のリソース、リソースのナビゲーション プロパティまたはサービスによって公開される関数またはアクションを対象とするエンドポイントに送信します。 エンドポイントは、URL で表されます。
Graph API エンドポイントの基本的な形式を次に示します。
https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}
URL は、次のコンポーネントで構成されます。
- サービス ルート: すべての Graph API の要求のサービス ルートは
https://graph.windows.netです。 - テナント ID {tenant_id}: 要求が対象とするテナントの ID です。
- リソース パス {resource_path}: 要求が対象とするリソース (ユーザー、グループなど) のパスです。
- Graph API バージョン {api_version}: 要求が対象とする Graph API のバージョンです。 これは、クエリ パラメーターで表され、必須です。
注: 場合によっては、リソース コレクションを読み取るときに、結果セットをフィルタ―処理、並べ替え、ページングする要求に OData のクエリ パラメーターを追加することができます。 詳細については、このトピックの「OData クエリ パラメーター」のセクションを参照してください。
テナント ID {tenant_id}
要求のターゲット テナントは、次の 4 つの方法のいずれかで指定できます。
テナント オブジェクト ID を使用。 この GUID はテナントの作成時に割り当てられます。 これは、TenantDetail オブジェクトの objectId プロパティで確認できます。 次の URL は、テナント オブジェクト ID を使用してユーザー リソース コレクションをアドレス指定する方法を示します。
https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6。確認済み (登録済み) のドメイン名を使用。 テナントに登録されている、いずれかのドメイン名です。 このドメイン名は、TenantDetail オブジェクトの verifiedDomains プロパティで確認できます。 次の URL は、ドメイン contoso.com を持つテナントのユーザー リソース コレクションをアドレス指定する方法を示します。
https://graph.windows.net/contoso.com/users?api-version=1.6。myOrganizationのエイリアスを使用。 このエイリアスは、OAuth 認証コード Grant type (3-legged) の場合、つまり委任されたアクセス許可スコープを使用する場合にのみ使用できます。 この別名では、大文字と小文字は区別されません。 これは、URL のオブジェクト ID またはテナント ドメインを置き換えます。 エイリアスが使用されると、Graph API は要求にアタッチされているトークンに表示される要求からテナントを取得します。 次の URL は、このエイリアスを使用してテナントのユーザー リソース コレクションをアドレス指定する方法を示します。
https://graph.windows.net/myorganization/users?api-version=1.6。meのエイリアスを使用。 このエイリアスは、OAuth 認証コード Grant type (3-legged) の場合、つまり委任されたアクセス許可スコープを使用する場合にのみ使用できます。 この別名では、大文字と小文字は区別されません。 これは、URL のオブジェクト ID またはテナント ドメインを置き換えます。 エイリアスが使用されると、Graph API は要求にアタッチされているトークンに表示される要求からユーザーを取得します。 次の URL は、このエイリアスを使用してサインインしたユーザーをアドレス指定します。https://graph.windows.net/me?api-version=1.6。
注: サインインしたユーザーに対する操作を指定するには、me エイリアスのみを使用します。 詳細については、「Signed-in User Operations (サインインしたユーザーの操作)」を参照してください。
リソース パス {resource_path}
リソース コレクション、個々のリソース、リソースのナビゲーション プロパティ、テナントで公開された関数またはアクション、リソースで公開された関数またはアクションのどれを対象としているかに応じて、異なる {resource_path} を指定します。
| Target | パス | 説明 |
|---|---|---|
| サービス メタデータ | /$metadata |
サービス メタデータ ドキュメントを返します。 次の例は、contoso.com テナントを使用するサービス メタデータを対象としています。 https://graph.windows.net/contoso.com/$metadata?api-version=1.6 注: サービス メタデータの読み取りには認証は必要ありません。 |
| リソース コレクション | /{resource_collection} |
テナントのユーザーやグループなどのリソース コレクションを対象とします。 このパスを使用して、コレクションのリソースを読み取ったり、リソースの種類に応じてテナントに新しいリソースを作成したりできます。 多くの場合、読み取りで返される結果セットは、結果をフィルター処理、並べ替え、またはページングするクエリ パラメーターを追加することでさらに絞り込むことができます。 次の例は、ユーザー コレクションを対象としています。 https://graph.windows.net/myorganization/users?api-version=1.6 |
| 1 つのリソース | /{resource_collection}/{resource_id} |
ユーザー、組織の連絡先、グループなどの、テナント内の特定のリソースを対象とします。 多くのリソースでは、resource_id がオブジェクト ID です。 一部のリソースでは追加の指定子が許可されます。たとえば、ユーザーをユーザー プリンシパル名 (UPN) で指定することもできます。 リソースによっては、このパスを使用して、リソースの宣言されたプロパティを取得したり、その宣言されたプロパティを変更したり、リソースを削除したりできます。 次の例は、ユーザー john@contoso.com を対象としています。 https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6 |
| ナビゲーション プロパティ (オブジェクト) | /{resource_collection}/{resource_id}/{property_name} |
ユーザーのマネージャーやグループのメンバーシップ、またはグループのメンバーなど、特定のリソースのナビゲーション プロパティを対象とします。 このパスを使用して、対象ナビゲーション プロパティによって参照されるオブジェクトを返すことができます。 次の例は、john@contoso.com のマネージャーを対象としています。 https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6 注: この形式のアドレス指定は読み取りの場合にのみ使用できます。 |
| ナビゲーション プロパティ (リンク) | /{resource_collection}/{resource_id}/$links/{property_name} |
ユーザーのマネージャーやグループのメンバーシップ、またはグループのメンバーなど、特定のリソースのナビゲーション プロパティを対象とします。 この形式のアドレス指定を使用すると、ナビゲーション プロパティの読み取りと変更の両方を行うことができます。 読み取り時には、プロパティによって参照されるオブジェクトは、応答本文で 1 つ以上のリンクとして返されます。 書き込み時には、オブジェクトは、要求本文で 1 つ以上のリンクとして指定されます。 次の例は、john@contoso.com のマネージャーのプロパティを対象としています。 https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6 |
| テナントで公開された関数またはアクション | /{function_name} |
テナントで公開された関数またはアクションを対象とします。 関数とアクションは、通常、POST 要求で起動し、要求本文を含めることができます。 次の例は、isMemberOf 関数を対象としています。 https://graph.windows.net/myorganization/isMemberOf?api-version=1.6。 |
| リソースで公開された関数またはアクション | /{resource_collection}/{resource_id}/{function_name} |
リソースで公開された関数またはアクションを対象とします。 関数とアクションは、通常、POST 要求で起動し、要求本文を含めることができます。 次の例は、getMemberGroups 関数を対象としています。 https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6。 |
Graph API バージョン {api-version}
api-version クエリ パラメーターを使用して、特定のバージョンの Graph API を操作の対象とします。 このパラメーターは必須です。
api-version パラメーターの値には、次のいずれかを指定できます。
- "beta"
- "1.6"
- "1.5"
- "2013/11/08"
- "2013/04/05"
たとえば、次の URL は、Graph API バージョン 1.6 を使用するユーザー コレクションを対象とします。
https://graph.windows.net/myorganization/users?api-version=1.6
各バージョンと、バージョン間での機能の変更の詳細については、「Versioning (バージョン)」を参照してください。
OData クエリ パラメーター
多くの場合、リソース コレクションを読み取るときに、OData クエリ パラメーターを要求に付け加えることで、結果セットをフィルター処理、並べ替え、およびページングすることができます。
Graph API では、次の OData クエリ パラメータをサポートしています。
- $filter
- $batch
- $expand
- $orderby
- $top
- $skiptoken および previous-page
Graph API でサポートされる OData クエリ パラメーターとその制限の詳細については、「サポートされているクエリ、フィルター、およびページング オプション」を参照してください。
要求および応答のヘッダー
次の表は、Graph API の要求で使用される一般的な HTTP ヘッダーを示します。 この説明は包括的なものではありません。
| 要求ヘッダー | 説明 |
|---|---|
| 承認 | 必須。 Azure Active Directory によって発行されるベアラー トークン。 詳細については、このトピックの「認証と承認」を参照してください。 |
| Content-Type | 要求本文がある場合に必要です。 要求本文のコンテンツのメディアの種類。 application/json を使用します。 メディアの種類にはパラメーターを含めることができます。 注: application/atom+xml および application/xml (リンク用) はサポートされますが、パフォーマンス上の理由、および XML のサポートが将来のリリースで廃止されるため、推奨されません。 |
| Content-Length | 要求本文がある場合に必要です。 要求の長さ (バイト単位)。 |
次の表は、Graph API の応答で返される一般的な HTTP ヘッダーを示します。 この説明は包括的なものではありません。
| 応答ヘッダー | 説明 |
|---|---|
| Content-Type | 応答本文のコンテンツのメディアの種類。 既定は、application/json です。 ユーザーのサムネイル写真の要求では、既定により image/jpeg が返されます。 |
| 場所 | ディレクトリに新しいリソース (オブジェクト) を作成する POST 要求に対する応答で返されます。 新しく作成されたリソースの URI が含まれています。 |
| ocp-aad-diagnostics-server-name | 要求された操作を実行したサーバーの ID。 |
| ocp-aad-session-key | ディレクトリ サービスでの現在のセッションを識別するキー。 |
少なくとも、要求ごとに次の操作を行うことをお勧めします。
- 要求を送信した正確なタイムスタンプを記録する。
client-request-idを送信してログを記録する。- HTTP 応答コードと
request-idのログを記録する。
このようなログの情報を提供することは、ヘルプやサポートを得る場合に Microsoft が問題をトラブルシューティングするために役立ちます。
要求および応答の本文
POST、PATCH、および PUT 要求の要求本文は、JSON または XML ペイロードで送信できます。 サーバーの応答は、JSON または XML ペイロードで返されます。 ペイロードは、要求本文で Content-Type 要求ヘッダーを使用して、および応答で Accept 要求ヘッダーを使用して指定することができます。
Graph API による要求と応答では JSON ペイロードを使用することを強くお勧めします。 これは、パフォーマンスのため、および XML が将来のリリースで廃止されることが理由です。
高度な機能
ここまでのセクションでは、Graph API による基本的な要求と応答の書式設定について説明しました。 より高度な機能では、追加のクエリ文字列パラメーターを追加したり、このトピックでこれまでに説明した基本の操作とは大幅に異なる要求と応答の本文を含めたりできます。
これには次の機能があります。
- バッチ処理: Graph API は、バッチ処理をサポートしています。 バッチ要求を送信することにより、サーバーへのラウンド トリップが短縮されるため、ネットワークのオーバーヘッドが減少し、操作を速く完了できるようになります。 Graph API によるバッチ処理の詳細については、「Batch Processing (バッチ処理)」を参照してください。
- 差分クエリ: Graph API は、差分クエリの実行をサポートしています。 差分クエリを使用すると、異なる時刻に発行された要求の間で、テナント内の特定のエンティティに行われた変更を返すことができます。 この機能は、ローカル ストアとテナントに対する変更を同期するためによく使用されます。 Graph API による差分クエリの詳細については、「Differential Query (差分クエリ)」を参照してください。