Microsoft Graph API を使用する

Microsoft Graph は、Microsoft Cloud サービス リソースへのアクセスを可能にする RESTful Web API です。アプリを登録 して、サービス または ユーザーの認証トークンを取得する と、Microsoft Graph API に対して要求を行うことができます。

重要: 条件付きアクセス ポリシーの Microsoft Graph への適用方法は変更されています。 条件付きアクセス ポリシーが構成されるシナリオを処理するよう、アプリケーションを更新する必要があります。 詳細およびガイダンスについては、「Azure Active Directory の条件付きアクセスについての開発者ガイド」を参照してください。

OData 名前空間

Microsoft Graph API は、そのほとんどのリソース、メソッド、および列挙型を Microsoft Graph メタデータの OData 名前空間microsoft.graphで定義します。 microsoft.graph.callRecordscallRecord などのリソースを定義する 通話レコード API など、少数の API セットがサブ名前空間に定義されています。

対応するトピックで明示的に指定されていない限り、種類、メソッド、および列挙型が microsoft.graph 名前空間の一部であると仮定します。

REST API メソッドを呼び出す

ユーザーや電子メール メッセージなど、リソースの読み取りや書き込みを行うには、次のような要求を構築します。

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

要求のコンポーネントには以下が含まれます。

  • {HTTP メソッド} - Microsoft Graph への要求で使用する HTTP メソッド。
  • {バージョン} - アプリケーションが使用している Microsoft Graph API のバージョン。
  • {リソース} - ユーザーが参照している Microsoft Graph のリソース。
  • {クエリ パラメーター} - 応答をカスタマイズするために使用する省略可能な OData クエリ オプションまたは REST メソッド パラメーター。

要求を行うと、次を含む応答が返されます。

  • 状態コード - 成功または失敗を示す HTTP 状態コード。HTTP エラー コードの詳細については、「エラー」を参照してください。
  • 応答メッセージ - 要求したデータ、または操作の結果。応答メッセージは、いくつかの操作で空になる場合があります。
  • nextLink - 要求が大量のデータを返す場合は、@odata.nextLink で返される URL を使用して応答をページングする必要があります。詳細については、「ページング」を参照してください。

HTTP メソッド

Microsoft Graph は、要求で HTTP メソッドを使用し、要求が何を行っているかを特定します。API は次のメソッドをサポートしています。

メソッド 説明
GET リソースからデータを読み取ります。
POST 新しいリソースを作成、または処理を実行します。
PATCH リソースを新しい値で更新します。
PUT リソースを新しいものと置換します。
DELETE リソースを削除します。
  • CRUD メソッドの GETDELETE では、要求本文は必要ありません。
  • POSTPATCH、および PUT メソッドは、通常 JSON 形式で指定されている要求本文を必要とし、それには、リソースのプロパティの値などの追加の情報が含まれます。

バージョン

Microsoft Graph は、現在 v1.0beta の 2 つのバージョンをサポートしています。

  • v1.0 には、一般公開されている API が含まれます。すべての運用アプリで、v1.0 バージョンを使用します。
  • beta には、現在プレビュー段階の API が含まれます。ベータ版 API に重大な変更を導入する可能性があるため、開発中のアプリのテストにのみ、ベータ版を使用することをお勧めします。運用アプリでは、ベータ版 API を使用しないでください。

ベータ版 API のフィードバックを常に募集しています。フィードバックの提供または機能のご要望は、「Microsoft 365 Developer プラットフォームのアイデア フォーラム」を参照してください。

API のバージョンに関する詳細については、「バージョン管理とサポート」を参照してください。

リソース

リソースには、エンティティまたは複合型が使用でき、一般的にプロパティを使用して定義されます。 エンティティは、常に "id" プロパティが含まれる点において、複合型とは異なります。

ユーザーの URL には、要求で操作するリソースが含まれます。たとえば meユーザーグループドライブ、および サイト などです。最上位のリソースそれぞれにも、リレーションシップ が含まれます。または me/messagesme/drive のように、追加のリソースにアクセスするのに使用できます。メソッド を使用して、リソースを操作することもできます。たとえば、電子メールを送信するには me/sendMail を使用します。詳細については、「Microsoft Graph 内を移動してデータとメソッドにアクセスする」を参照してください。

各リソースにアクセスするために異なるアクセス許可が必要になる可能性があります。リソースの作成または更新には、リソースの読み取りよりも高いレベルのアクセス許可が必要になります。必要なアクセス許可に関する詳細については、メソッドの参照トピックを参照してください。

アクセス許可に関する詳細については、「アクセス許可の参照」を参照してください。

クエリ パラメーター

クエリ パラメーターには、OData のシステム クエリ オプション、または応答をカスタマイズするためにメソッドが受け入れる文字列を使用できます。

省略可能の OData のシステム クエリ オプションを使用すると、既定の応答よりも多い、または少ないプロパティを含めたり、カスタム クエリに一致するアイテムについて応答をフィルター処理したり、メソッドの追加のパラメーターを提供したりできます。

たとえば、次の filter パラメーターを追加すると、jon@contoso.comemailAddress プロパティを持つメッセージのみが返されるように制限できます。

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

OData クエリ オプションの詳細については、「Use query parameters to customize responses (クエリパラメーターを使用して応答をカスタマイズする)」を参照してください。

OData クエリ オプション以外に、一部のメソッドでは、クエリ URL の一部としてパラメーター値を指定することが要求されます。 たとえば、ある一定期間内にユーザーの予定表で発生したイベントのコレクションを取得するには、クエリ パラメーターとして startDateTimeendDateTime の値を使用して期間を指定し、usercalendarView リレーションシップに対してクエリを実行します。

GET https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

Microsoft Graph を操作するためのツール

Graph エクスプローラー

Graph エクスプローラーは、Microsoft Graph API を使用して要求を構築およびテストするために使用できる Web ベースのツールです。https://developer.microsoft.com/graph/graph-explorer でGraph エクスプローラーにアクセスできます。

サインインせずにデモ データにアクセスすることも、独自のテナントにサインインすることもできます。次の手順を使用して要求を構築します。

  1. HTTP メソッドを選択します。
  2. 使用する API のバージョンを選択します。
  3. [要求] テキスト ボックスにクエリを入力します。
  4. [クエリの実行] を選択します。

次の例では、デモ テナントのユーザーに関する情報を返す要求を示します。

GET ユーザー要求が強調表示された Graph エクスプローラーのスクリーンショット

Graph エクスプローラーでは、一般的な要求をすばやく実行できるようにサンプル クエリが用意されています。 使用可能なサンプルを確認するには、[サンプルをさらに表示] を選択します。 表示するサンプルのセットで [オン] を選択し、選択ウィンドウを閉じると、定義済みの要求の一覧が表示されます。

要求が送信された後に、状態コードとメッセージが表示され、[応答のプレビュー] タブに応答が表示されます。

Postman

Postman は、Microsoft Graph API を使用して要求を構築およびテストするために使用できる Web ベースのツールです。 Postman は https://www.getpostman.com/ からダウンロードできます。 Postman で Microsoft Graph を操作するには、Microsoft Graph コレクションを使用します。

詳細については、「Microsoft Graph API で Postman を使用する」をご覧ください。

次の手順

Microsoft Graph を使用して、起動および実行する準備ができました。詳細について知るには、クイック スタートを試したり、「SDK とコード サンプル」のいずれかを使用して開始したりします。