Microsoft Graph API を使用するUse the Microsoft Graph API

Microsoft Graph は、Microsoft Cloud サービス リソースへのアクセスを可能にする RESTful Web API です。アプリを登録 して、サービス または ユーザーの認証トークンを取得する と、Microsoft Graph API に対して要求を行うことができます。Microsoft Graph is a RESTful web API that enables you to access Microsoft Cloud service resources. After you register your app and get authentication tokens for a user or service, you can make requests to the Microsoft Graph API.

重要: 条件付きアクセス ポリシーの Microsoft Graph への適用方法は変更されています。Important: How conditional access policies apply to Microsoft Graph is changing. 条件付きアクセス ポリシーが構成されるシナリオを処理するよう、アプリケーションを更新する必要があります。Applications need to be updated to handle scenarios where conditional access policies are configured. 詳細およびガイダンスについては、「Azure Active Directory の条件付きアクセスについての開発者ガイド」を参照してください。For more information and guidance, see Developer Guidance for Azure Active Directory Conditional Access.

ユーザーや電子メール メッセージなど、リソースの読み取りや書き込みを行うには、次のような要求を構築します。To read from or write to a resource such as a user or an email message, you construct a request that looks like the following.

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

要求のコンポーネントには以下が含まれます。The components of a request include:

  • {HTTP メソッド} - Microsoft Graph への要求で使用する HTTP メソッド。{HTTP method} - The HTTP method used on the request to Microsoft Graph.
  • {バージョン} - アプリケーションが使用している Microsoft Graph API のバージョン。{version} - The version of the Microsoft Graph API your application is using.
  • {リソース} - ユーザーが参照している Microsoft Graph のリソース。{resource} - The resource in Microsoft Graph that you're referencing.
  • {クエリ パラメーター} - 応答をカスタマイズするために使用する省略可能な OData クエリ オプションまたは REST メソッド パラメーター。{query-parameters} - Optional OData query options or REST method parameters that customize the response.

要求を行うと、次を含む応答が返されます。After you make a request, a response is returned that includes:

  • 状態コード - 成功または失敗を示す HTTP 状態コード。HTTP エラー コードの詳細については、「エラー」を参照してください。Status code - An HTTP status code that indicates success or failure. For details about HTTP error codes, see Errors.
  • 応答メッセージ - 要求したデータ、または操作の結果。応答メッセージは、いくつかの操作で空になる場合があります。Response message - The data that you requested or the result of the operation. The response message can be empty for some operations.
  • nextLink - 要求が大量のデータを返す場合は、@odata.nextLink で返される URL を使用して応答をページングする必要があります。詳細については、「ページング」を参照してください。nextLink - If your request returns a lot of data, you need to page through it by using the URL returned in @odata.nextLink. For details, see Paging.

HTTP メソッドHTTP methods

Microsoft Graph は、要求で HTTP メソッドを使用し、要求が何を行っているかを特定します。API は次のメソッドをサポートしています。Microsoft Graph uses the HTTP method on your request to determine what your request is doing. The API supports the following methods.

メソッドMethod 説明Description
GETGET リソースからデータを読み取ります。Read data from a resource.
POSTPOST 新しいリソースを作成、または処理を実行します。Create a new resource, or perform an action.
PATCHPATCH リソースを新しい値で更新します。Update a resource with new values.
PUTPUT リソースを新しいものと置換します。Replace a resource with a new one.
DELETEDELETE リソースを削除します。Remove a resource.
  • CRUD メソッドの GETDELETE では、要求本文は必要ありません。For the CRUD methods GET and DELETE, no request body is required.
  • POSTPATCH、および PUT メソッドは、通常 JSON 形式で指定されている要求本文を必要とし、それには、リソースのプロパティの値などの追加の情報が含まれます。The POST, PATCH, and PUT methods require a request body, usually specified in JSON format, that contains additional information, such as the values for properties of the resource.

バージョンVersion

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

  • v1.0 には、一般公開されている API が含まれます。すべての運用アプリで、v1.0 バージョンを使用します。v1.0 includes generally available APIs. Use the v1.0 version for all production apps.
  • beta には、現在プレビュー段階の API が含まれます。ベータ版 API に重大な変更を導入する可能性があるため、開発中のアプリのテストにのみ、ベータ版を使用することをお勧めします。運用アプリでは、ベータ版 API を使用しないでください。beta includes APIs that are currently in preview. Because we might introduce breaking changes to our beta APIs, we recommend that you use the beta version only to test apps that are in development; do not use beta APIs in your production apps.

ベータ版 API のフィードバックを常に募集しています。フィードバックの提供または機能のご要望は、「UserVoice」ページを参照してください。We are always looking for feedback on our beta APIs. To provide feedback or request features, see our UserVoice page.

API のバージョンに関する詳細については、「バージョン管理とサポート」を参照してください。For more information about API versions, see Versioning and support.

リソースResource

リソースには、エンティティまたは複合型が使用でき、一般的にプロパティを使用して定義されます。A resource can be an entity or complex type, commonly defined with properties. エンティティは、常に "id" プロパティが含まれる点において、複合型とは異なります。Entities differ from complex types by always including an id property.

ユーザーの URL には、要求で操作するリソースが含まれます。たとえば、meusergroupdrivesite などです。Your URL will include the resource you are interacting with in the request, such as me, user, group, drive, and site. 多くの場合、最上位のリソースには _リレーションシップ_も含まれます。me/messages または me/drive のように、追加のリソースにアクセスするのに使用できます。Often, top-level resources also include relationships, which you can use to access additional resources, like me/messages or me/drive. _メソッド_を使用して、リソースを操作することもできます。たとえば、電子メールを送信するには me/sendMail を使用します。You can also interact with resources using methods; for example, to send an email, use me/sendMail. 詳細については、「Microsoft Graph 内を移動してデータとメソッドにアクセスする」を参照してください。For more information, see Access data and methods by navigating Microsoft Graph.

各リソースにアクセスするために異なるアクセス許可が必要になる可能性があります。リソースの作成または更新には、リソースの読み取りよりも高いレベルのアクセス許可が必要になります。必要なアクセス許可に関する詳細については、メソッドの参照トピックを参照してください。Each resource might require different permissions to access it. You will often need a higher level of permissions to create or update a resource than to read it. For details about required permissions, see the method reference topic.

アクセス許可に関する詳細については、「アクセス許可の参照」を参照してください。For details about permissions, see Permissions reference.

クエリ パラメーターQuery parameters

クエリ パラメーターには、OData のシステム クエリ オプション、または応答をカスタマイズするためにメソッドが受け入れる文字列を使用できます。Query parameters can be OData system query options, or other strings that a method accepts to customize its response.

省略可能の OData のシステム クエリ オプションを使用すると、既定の応答よりも多い、または少ないプロパティを含めたり、カスタム クエリに一致するアイテムについて応答をフィルター処理したり、メソッドの追加のパラメーターを提供したりできます。You can use optional OData system query options to include more or fewer properties than the default response, filter the response for items that match a custom query, or provide additional parameters for a method.

たとえば、次の filter パラメーターを追加すると、jon@contoso.comemailAddress プロパティを持つメッセージのみが返されるように制限できます。For example, adding the following filter parameter restricts the messages returned to only those with the emailAddress property of jon@contoso.com.

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

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

OData クエリ オプション以外に、一部のメソッドでは、クエリ URL の一部としてパラメーター値を指定することが要求されます。Aside from OData query options, some methods require parameter values specified as part of the query URL. たとえば、ある一定期間内にユーザーの予定表で発生したイベントのコレクションを取得するには、クエリ パラメーターとして startDateTimeendDateTime の値を使用して期間を指定し、usercalendarView リレーションシップに対してクエリを実行します。For example, you can get a collection of events that occurred during a time period in a user's calendar, by querying the calendarView relationship of a user, and specifying the period startDateTime and endDateTime values as query parameters:

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

次のステップNext steps

Microsoft Graph を使用して、起動および実行する準備ができました。詳細について知るには、Graph エクスプローラーに移動して、いくつかの要求やクイック スタートを試したり、「SDK とコード サンプル」のいずれかを使用して開始したりします。You're ready to get up and running with Microsoft Graph. To learn more, go to the Graph Explorer to try out some requests, try the Quick Start, or get started using one of our SDKs and code samples.