REST を使って Microsoft Graph に対してクエリを実行する
Microsoft Graph は RESTful Web API であり、それを使用すると Microsoft Cloud サービス リソースにアクセスできます。 アプリを登録し、ユーザーまたはサービスのための認証トークンを取得した後、Microsoft Graph API に要求を行うことができます。
Microsoft Graph API では、OData 名前空間 microsoft.graph のリソース、メソッド、列挙型のほとんどが、Microsoft Graph メタデータで定義されています。 少数の API セットがそのサブ名前空間で定義されています。たとえば、microsoft.graph.callRecords の callRecord のようなリソースを定義する 呼び出しレコード API などです。
対応するトピックで明示的に指定されていない限り、型、メソッド、列挙型は microsoft.graph 名前空間に含まれていると想定してください。
REST API メソッドを呼び出す
ユーザーやメール メッセージなどのリソースを読み取るか、書き込むには、次のサンプルような要求を作成します:
{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}
要求のコンポーネントには次のものが含まれています。
{HTTP method}- Microsoft Graph への要求で使う HTTP メソッド。{version}- アプリケーションで使っている Microsoft Graph API のバージョン。{resource}- 参照している Microsoft Graph 内のリソース。{query-parameters}- 応答をカスタマイズする OData クエリ オプションまたは REST メソッドパラメーター (省略可能)。
要求を行った後、次のものを含む応答が返されます。
- 状態コード - 成功または失敗を示す HTTP 状態コード。
- 応答メッセージ - 要求したデータまたは操作の結果。 一部の操作では、応答メッセージが空になる可能性があります。
nextLink- 要求に対して大量のデータが返された場合は、@odata.nextLinkで返された URL を使ってページングする必要があります。
HTTP メソッド
Microsoft Graph では、要求に対して HTTP メソッドを使い、要求の内容を判断します。 API では次のメソッドがサポートされています。
| Method | 説明 |
|---|---|
| GET | リソースからデータを読み取ります。 |
| POST | 新しいリソースを作成するか、アクションを実行します。 |
| PATCH | 新しい値でリソースを更新します。 |
| PUT | リソースを新しいものに置き換えます。 |
| DELETE | リソースを削除します。 |
- CRUD メソッド
GETとDELETEの場合、要求本文は必要ありません。 POST、PATCH、PUTの各メソッドには、追加情報を含む要求本文 (JSON 形式で指定) が必要です。 リソースのプロパティの値などです。
Version
現在、Microsoft Graph では、v1.0 と beta の 2 つのバージョンがサポートされています。
v1.0には一般提供されている API が含まれています。 すべての運用アプリでは、v1.0 を使用してください。betaには、現在プレビュー段階にある API が含まれています。 ベータ版 API は破壊的に変更される可能性があるため、ベータ版は開発中のアプリをテストする場合にのみ使用することをお勧めします。運用アプリではベータ版 API を使用しないでください。
リソース
リソースはエンティティまたは複合型にすることができ、一般的にはプロパティを使って定義されます。 エンティティは、常に id プロパティが含まれる点で複合型と異なっています。
URL には、要求で対話するリソースが含まれます。たとえば、me、user、group、drive、site です。 多くの場合、トップレベル リソースには "リレーションシップ" も含まれており、me/messages や me/drive などの他のリソースにアクセスするために使用できます。 また、"メソッド" を使ってリソースと対話することもできます。たとえば、メールを送信する場合は me/sendMail を使います。
リソースにアクセスするには、リソースごとに異なるアクセス許可が必要になる場合があります。 リソースを作成または更新するには、リソースを読み取る場合よりも高いレベルのアクセス許可が必要になることが頻繁にあります。 必要なアクセス許可の詳細については、メソッドのリファレンス トピックを参照してください。
クエリ パラメーター
クエリ パラメーターは、OData システム クエリ オプションや、メソッドの応答をカスタマイズするためにメソッドに指定するその他の文字列にすることができます。
オプションの OData システム クエリ オプションを使用して、既定の応答よりも多くのプロパティまたは少数のプロパティを含めることができます。 カスタム クエリに一致する項目の応答をフィルター処理する、またはメソッドに別のパラメーターを指定することができます。
たとえば、次の filter パラメーターを追加すると、返されるメッセージが jon@contoso.com という emailAddress プロパティを持つもに制限されます。
GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'
その他のリソース
Microsoft Graph API を使用して要求を作成し、テストするために使用できるいくつかのツールへのリンクを以下に示します。