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.

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.
  • {version} - アプリケーションが使用している Microsoft Graph API のバージョン。{version} - The version of the Microsoft Graph API your application is using.
  • {resource} - ユーザーが参照している Microsoft Graph のリソース。{resource} - The resource in Microsoft Graph that you're referencing.
  • クエリ パラメーター - 要求または応答を変更するパラメーターのオプションのセット。query-parameters - An optional set of parameters to modify the request or 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.
  • [次へ] リンク - 要求が大量のデータを返す場合は、[次ヘ] を選択して、ページを進める必要があります。詳細については、「ページング」を参照してください。Next link - If your request returns a lot of data, you need to page through it by choosing Next. 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.
  • メソッド GETDELETE では、要求本文は必要ありません。For the 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

ユーザーの URL には、要求で操作するリソースが含まれます。たとえば、meusersgroupsdrivessites などです。最上位のリソースそれぞれにも、リレーションシップが含まれます。me/messages または me/drive のように、追加のリソースにアクセスするのに使用できます。メソッド を使用して、リソースを操作することもできます。たとえば、電子メールを送信するには me/sendMail を使用します。Your URL will include the resource or resources you are interacting with in the request, such as me, users, groups, drives, and sites. Each of the top-level resources also include relationships, which you can use to access additional resources, like me/messages or me/drive. You can also interact with resources using methods; for example, to send an email, use me/sendMail.

リソースのリレーションシップおよびメソッドを移動する方法の詳細については、「グラフをスキャンする」を参照してください。For more information about how to navigate resource relationships and methods, see Traverse the 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 (optional)

Microsoft Graph アプリで応答をカスタマイズするには、オプションのクエリ パラメーターを使用できます。クエリ パラメーターを使用して、既定の応答よりも多い、または少ないプロパティを含めたり、カスタム クエリに一致するアイテムの応答をフィルター処理したり、メソッドの追加のパラメーターを提供したりします。You can use optional query parameters to customize the response in your Microsoft Graph app. Use query parameters 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.

たとえば、次のフィルター パラメーターを追加すると、メッセージが 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.

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

クエリ パラメーターに関する詳細については、「応答をカスタマイズする」を参照してください。For more information about query parameters, see Customize responses.

次のステップ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.