次の方法で共有

Microsoft Graph API を使用する

  • [アーティクル]

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

重要

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

OData 名前空間

Microsoft Graph API は、そのほとんどのリソース、メソッド、および列挙型を Microsoft Graph メタデータの OData 名前空間microsoft.graphで定義します。 microsoft.graph.callRecords の callRecord などのリソースを定義する 通話レコード 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 メソッド パラメーター。
  • {headers} - 要求をカスタマイズする要求ヘッダー。 API に応じて、省略可能または必須にすることができます。

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

  • 状態コード - 成功または失敗を示す HTTP 状態コード。 HTTP エラー コードの詳細については、「エラー」を参照してください。
  • 応答メッセージ - 要求したデータ、または操作の結果。 一部の操作では、応答メッセージを空にすることができます。
  • @odata.nextLink - 要求が大量のデータを返す場合は、 で @odata.nextLink返される URL を使用してページを表示する必要があります。 詳細については、「ページング」を参照してください。
  • 応答ヘッダー - 返されるコンテンツの種類や、応答を要求に関連付けるために使用できる要求 ID など、応答に関する追加情報。

HTTP メソッド

Microsoft Graph では、要求に対して HTTP メソッドを使用して、要求が何を行っているかを判断します。 リソースによっては、API は、以下で説明するアクション、関数、CRUD 操作などの操作をサポートする場合があります。

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

重要

Microsoft Graph APIの書き込み要求のサイズ制限は 4 MB です。

場合によっては、実際の書き込み要求サイズの制限が 4 MB より小さくなります。 たとえば、base64 でエンコードされた場合、約 3.5 MB のファイルが 4 MB を超える場合があるため、ユーザー イベントに POST /me/events/{id}/attachments を添付する場合、要求サイズの制限は 3 MB です。

サイズ制限を超える要求は、状態コード HTTP 413 で失敗し、"要求エンティティが大きすぎる" または "ペイロードが大きすぎる" というエラー メッセージが表示されます。

バージョン

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

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

ベータ版 API のフィードバックを常に募集しています。 フィードバックの提供、機能のリクエストを行うには、 「Microsoft 365 Developer プラットフォームのアイデア フォーラム」 を参照します。

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

リソース

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

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

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

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

クエリ パラメーター

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

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

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

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

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

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

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

ヘッダー

Microsoft Graph では、HTTP 標準ヘッダーとカスタム ヘッダーの両方がサポートされています。

特定の API では、要求に追加のヘッダーを含める必要がある場合があります。 一方、Microsoft Graph は常に必須ヘッダー (応答のヘッダーなどrequest-id) を返します。また、一部のヘッダーは一部の API や機能に固有である場合があります。たとえば、アプリが調整制限に達したときにヘッダーが含まれる場合やLocation、Retry-After実行時間の長い操作に含まれるヘッダーなどです。

RFC 9110 で定義されているヘッダーでは、特に明示的に指定されていない限り、大文字と小文字は区別されません。

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

Graph エクスプローラー

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

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

  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 とコード サンプルのいずれかを使用して作業を開始します。