Microsoft Graph の操作に関するベスト プラクティスBest practices for working with Microsoft Graph

この記事では、アプリケーションで Microsoft Graph を最大限に活用するのに役立つベスト プラクティスについて説明します。これには、Microsoft Graph の概要、アプリのパフォーマンス向上、エンドユーザーに対してアプリケーションの信頼性を高める方法が含まれます。This article describes best practices that you can apply to help your applications get the most out of Microsoft Graph - whether that involves learning about Microsoft Graph, improving app performance, or making your application more reliable for end users.

Graph エクスプローラーを使用して API を理解するUse Graph Explorer to get to know the API

Microsoft Graph で利用できるデータについての理解を深める最も良い方法は、Graph エクスプローラーを使用してみることです。The easiest way to start exploring the data available through Microsoft Graph is to use Graph Explorer. Graph エクスプローラーを使用すると、CRUD をすべてサポートした REST 要求を作成し、HTTP 要求ヘッダーを適合させて、データ応答を確認できます。Graph Explorer lets you craft REST requests (with full CRUD support), adapt the HTTP request headers, and see the data responses. Graph エクスプローラーには、作業の開始に役立つ一連のサンプル クエリが用意されています。To help you get started, Graph Explorer also provides a set of sample queries.

新しい API をアプリケーションに統合する前に、それらを試してみてください。Experiment with new APIs before you integrate them into your application.

認証Authentication

Microsoft Graph のデータにアクセスするには、アプリケーションが OAuth 2.0 アクセス トークンを取得し、次のいずれかの方法でそれを Microsoft Graph に提示する必要があります。To access the data in Microsoft Graph, your application will need to acquire an OAuth 2.0 access token, and present it to Microsoft Graph in either of the following:

  • HTTP Authorization 要求ヘッダー (Bearer トークンとして)The HTTP Authorization request header, as a Bearer token
  • グラフ クライアント コンストラクター (Microsoft Graph クライアント ライブラリを使用する場合)The graph client constructor, when using a Microsoft Graph client library

Microsoft Authentication Library API (MSAL) を使用して、Microsoft Graph へのアクセス トークンを取得します。Use the Microsoft Authentication Library API, MSAL to acquire the access token to Microsoft Graph.

アプリで同意と承認を行うには、次のベスト プラクティスを適用します。Apply the following best practices for consent and authorization in your app:

  • 最小限の権限を使用するUse least privilege. 絶対に必要なアクセス許可のみを、本当に必要な場合に限って要求します。Only request permissions that are absolutely necessary, and only when you need them. アプリケーションが呼び出す API の場合、メソッドに関するトピックの「アクセス許可」セクションを確認し (例として「ユーザーを作成する」をご覧ください)、必要最小限の権限が付与されたアクセス許可を選択します。For the APIs your application calls, check the permissions section in the method topics (for example, see creating a user, and choose the least privileged permissions. アクセス許可の完全な一覧については、「アクセス許可のリファレンス」をご覧ください。For a full list of permissions, see permissions reference.

  • シナリオに応じて適切なアクセス許可の種類を使用するUse the correct permission type based on scenarios. サインインしているユーザーが存在している対話型のアプリケーションを作成する場合、そのアプリケーションは委任されたアクセス許可を使用する必要があります。これにより、アプリケーションはアクセス許可を委任され、Microsoft Graph に呼び出しを行う際にサインインしているユーザーとして動作します。If you're building an interactive application where a signed in user is present, your application should use delegated permissions, where the application is delegated permission to act as the signed-in user when making calls to Microsoft Graph. ただし、バックグラウンド サービスまたはデーモンなど、サインインしているユーザーなしで動作するアプリケーションの場合は、アプリケーションのアクセス許可を使用する必要があります。If, however, your application runs without a signed-in user, such as a background service or daemon, your application should use application permissions.

    注: アプリケーションのアクセス許可を対話型のシナリオで使用すると、アプリケーションがコンプライアンスやセキュリティ上のリスクにさらされる恐れがあります。Note: Using application permissions for interactive scenarios can put your application at compliance and security risk. これにより、ユーザーの権限を誤って昇格させ、管理者によって設定されたポリシーを回避してデータにアクセスできるようにしてしまう可能性があります。It can inadvertantly elevate a user's privileges to access data, circumnavigating policies configured by an administrator.

  • 慎重にアプリを構成するBe thoughtful when configuring your app. これは、エンドユーザーや管理者のエクスペリエンス、およびアプリケーションの導入とセキュリティに直接影響します。This will directly affect end user and admin experiences, along with application adoption and security. 例:For example:

    • アプリケーションのプライバシーに関する声明、使用条件、名前、ロゴ、ドメインは、同意その他の操作で表示されるので、エンドユーザーが理解できるように慎重に構成する必要があります。Your application's privacy statement, terms of use, name, logo and domain will show up in consent and other experiences - so make sure to configure these carefully so they are understood by your end-users.
    • アプリケーションに同意するのがどのようなユーザーなのか (エンドユーザーか管理者か) を考慮した上で、アプリケーションが適切なアクセス許可を要求するように構成します。Consider who will be consenting to your application - either end users or administrators - and configure your application to request permissions appropriately.
    • 静的、動的、増分同意の違いを確実に理解している必要があります。Ensure that you understand the difference between static, dynamic and incremental consent.
  • マルチテナント アプリケーションを考慮するConsider multi-tenant applications. ユーザーによって、アプリケーションや同意のコントロールはまちまちで、その状態もさまざまであることを想定します。Expect customers to have various application and consent controls in different states. 例:For example:

    • テナント管理者は、エンドユーザーがアプリケーションに同意する機能を無効にできます。Tenant administrators can disable the ability for end users to consent to applications. この例では、管理者がユーザーに代わって同意する必要があります。In this case, an administrator would need to consent on behalf of their users.
    • テナント管理者は、ユーザーが他のユーザーのプロファイルを読み取れないようにする場合や、セルフ サービスのグループ作成を限られたユーザーのみに限定する場合のように、カスタム承認ポリシーを設定できます。Tenant administrators can set custom authorization policies such as blocking users from reading other user's profiles, or limiting self-service group creation to a limited set of users. この例では、アプリケーションがあるユーザーの代理として動作している場合、そのアプリケーションが 403 エラー応答を処理することを想定する必要があります。In this case, your application should expect to handle 403 error response when acting on behalf of a user.

応答を効果的に処理するHandle responses effectively

Microsoft Graph に対して行う要求に応じて、アプリケーションがさまざまな種類の応答を処理できるようにしておく必要があります。Depending on the requests you make to Microsoft Graph, your applications should be prepared to handle different types of responses. エンドユーザーがアプリケーションの動作を信頼し予測できるようにするために従う必要のある、最も重要なプラクティスの一部を次に示します。The following are some of the most important practices to follow to ensure that your application behaves reliably and predictably for your end users.

改ページPagination

リソース コレクションのクエリを実行する場合、Microsoft Graph が返す結果セットは、サーバー側のページ サイズ制限が原因で複数ページになることを想定する必要があります。When querying a resource collection, you should expect that Microsoft Graph will the return result set in multiple pages, due to server-side page size limits. 要求セットが複数ページにまたがる場合、Microsoft Graph は、結果の次ページへの URL を格納する @odata.nextLink プロパティを応答で返します。When a result set spans multiple pages, Microsoft Graph returns an @odata.nextLink property in the response that contains a URL to the next page of results.

たとえば、サインインしているユーザーを一覧表示する次のようなメッセージの場合、For example, listing the signed-in users messages:

GET https://graph.microsoft.com/v1.0/me/messages

結果セットがサーバー側のページ サイズ制限を超えると、@odata.nextLink プロパティを格納した応答が返されます。Would return a response containing an @odata.nextLink property, if the result set exceeds the server-side page size limit.

"@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=23"

注: 作成するアプリケーションは、応答が実際にページングされている可能性を常に考慮し、結果の次ページのセットを取得する @odata.nextLink プロパティを使用して、結果セットのページを最後まですべて読み取るようにする必要があります。Note: Your application should always handle the possibility that the responses are paged in nature, and use the @odata.nextLink property to obtain the next paged set of results, until all pages of the result set have been read. 最後のページには、@odata.nextLink プロパティが含まれません。The final page will not contain an @odata.nextLink property. 結果の次ページを要求する際は、その URL 全体を符号化文字列として処理して @odata:nextLink プロパティに格納する必要があります。You should include the entire URL in the @odata:nextLink property in your request for the next page of results, treating the entire URL as an opaque string.

詳しくは、「ページング」をご覧ください。For more details, see paging.

予想されるエラーの処理Handling expected errors

アプリケーションはすべてのエラー応答 (400 および 500 の範囲) を処理する必要がありますが、次の表に示す、予想される特定のエラーと応答に特に注意を払う必要があります。While your application should handle all error responses (in the 400 and 500 ranges), pay special attention to certain expected errors and responses, listed in the following table.

トピックTopic HTTP エラー コードHTTP error code ベスト プラクティスBest practice
ユーザーにアクセス権がありませんUser does not have access 403403 アプリケーションが起動して実行している場合、同意エクスペリエンスで必要なアクセス許可を与えられていても、このエラーが発生することがあります。If your application is up and running, it could encounter this error even if it has been granted the necessary permissions through a consent experience. この場合、最も考えられるのは、要求されたリソースにアクセスする権限を、サインインしているユーザーが持っていないことです。In this case, it's most likely that the signed-in user does not have privileges to access the resource requested. アプリケーションは、サインインしているそのユーザーに、汎用の「アクセスが拒否されました」というエラーを返す必要があります。Your application should provide a generic "Access denied" error back to the signed-in user.
見つかりませんNot found 404404 場合によっては、要求されたリソースが検出できないことがあります。In certain cases, a requested resource might not be found. たとえば、リソースが存在しない、プロビジョニングが済んでいない (ユーザーの写真など)、削除されているなどのケースが考えられます。For example a resource might not exist, because it has not yet been provisioned (like a user's photo) or because it has been deleted. 削除された一部のリソース (ユーザー、グループ、アプリケーション リソースなど) は、削除から 30 日以内であれば完全に復元される可能性があるため、アプリケーションはこの点も考慮に入れる必要があります。Some deleted resources might be fully restored within 30 days of deletion - such as user, group and application resources, so your application should also take this into account.
スロットルThrottling 429429 API は、さまざまな理由から常にスロットルと呼ばれる状態になる可能性があります。このため、アプリケーションは常に 429 応答を処理できるようにしておく必要があります。APIs might throttle at any time for a variety of reasons, so your application must always be prepared to handle 429 responses. このエラー応答には、Retry-After フィールドが HTTP 応答ヘッダーに格納されています。This error response includes the Retry-After field in the HTTP response header. Retry-After の延期期間を使用して要求を一旦取り消すことが、最も迅速にスロットルを解消する方法です。Backing off requests using the Retry-After delay is the fastest way to recover from throttling. 詳細については、「スロットル」をご覧ください。For more information, see throttling.
サービスを使用できませんService unavailable 503503 サービスが使用中の可能性があります。This is likely because the services is busy. 429 と同様に、要求を一旦取り消す方法を採用する必要があります。You should employ a back-off strategy similar to 429. さらに、新しい HTTP 接続経由で再試行要求を新たに作成することが常に必要です。Additionally, you should always make new retry requests over a new HTTP connection.

Evolvable 列挙型Evolvable enums

クライアント アプリケーションは、既存の列挙型にメンバーを追加することで分割される場合があります。Client applications can be broken by the addition of members to an existing enum. Microsoft Graph の新しい列挙型の一部では、重大な変更を加えずに新規メンバーを追加できるようにするメカニズムが用意されています。For some newer enums in Microsoft Graph, a mechanism is available to allow for adding new members without incurring a breaking change. これらの新しい列挙型では、unknownFutureValue と呼ばれる共通の標識メンバーにより、既知の列挙型メンバーと不明な列挙型メンバーが区別されます。On these newer enums, you'll see a common sentinel member called unknownFutureValue that demarcates known and unknown enum members. 既知のメンバーにはこの標識メンバーより小さい値が指定され、不明なメンバーには大きな値が指定されます。Known members will have a number less than the sentinel member, while unknown members will be greater in value. 既定では、Microsoft Graph は不明なメンバーを返しません。By default, unknown members are not returned by Microsoft Graph. アプリケーションが不明なメンバーを処理するように作成されている場合、HTTP Prefer 要求ヘッダーを使用して不明な列挙型メンバーを受け取るようにオプトインできます。If, however, your application is written to handle the appearance of unknown members, it can opt-in to receive unknown enum members, using an HTTP Prefer request header.

注: アプリケーションが不明なメンバーを処理できるようになっている場合、次のように HTTP prefer 要求ヘッダーを使用してオプトインする必要があります。Prefer: include-unknown-enum-membersNote: If your application is prepared to handle unknown enum members, it should opt-in by using an HTTP prefer request header: Prefer: include-unknown-enum-members.

ローカルにデータを保存するStoring data locally

アプリケーションは、Microsoft Graph に対して呼び出しを実行し、必要に応じてリアルタイムでデータを取得するのが理想的です。Your application should ideally make calls to Microsoft Graph to retrieve data in real time as necessary. 特定のシナリオに必要な場合に限って、データをローカルにキャッシュし保存するようにします。そのようなユース ケースが使用条件やプライバシー ポリシーの対象となっている場合は、「Microsoft API の利用規約」に違反しないようにする必要があります。You should only cache or store data locally if required for a specific scenario, and if that use case is covered by your terms of use and privacy policy, and does not violate the Microsoft APIs Terms of Use. 適切な保持ポリシーと削除ポリシーをアプリケーションに実装する必要もあります。Your application should also implement proper retention and deletion policies.

最適化Optimizations

一般に、パフォーマンス、セキュリティ、プライバシー保護などの理由から、アプリケーションが本当に必要とするデータのみを取得するようにする必要があります。In general, for performance and even security or privacy reasons, you should only get the data your application really needs, and nothing more.

使用予測Use projections

アプリケーションで本当に必要となるプロパティのみを選択します。これにより、不要なネットワーク トラフィックだけでなく、アプリケーション (やサービス) での不要なデータ処理を削減できます。Choose only the properties your application really needs and no more, because this saves unnecessary network traffic and data processing in your application (and in the service).

注: クエリから返されるプロパティをアプリケーションで必要なものだけに制限するには、$select クエリ パラメーターを使用します。Note: Use the $select query parameter to limit the properties returned by a query to those needed by your application.

たとえば、サインイン ユーザーのメッセージを取得するとき、from プロパティと subject プロパティだけを返すよう指定できます。For example, when retrieving the messages of the signed-in user, you can specify that only the from and subject properties be returned:

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject

最低限の応答を取得するGetting minimal responses

PUT、PATCH (および一部の POST) などのいくつかの操作では、アプリケーションで応答ペイロードを利用する必要がない場合、API が最低限のデータを返すようにできます。For some operations, such as PUT and PATCH (and in some cases POST), if your application doesn't need to make use of a response payload, you can ask the API to return minimal data. 一部のサービスでは、PUT 操作や PATCH 操作に対して既に「204 No Content」応答が返されています。Note that some services already return a 204 No Content response for PUT and PATCH operations.

注: 適切な場合は、HTTP 要求ヘッダーを次のように使用して、最低限の表示応答を要求します。Prefer: return=minimalNote: Request minimal representation responses using an HTTP request header where appropriate: Prefer: return=minimal. ただし、作成操作ではこの処理が不適切な場合があることにご注意ください。これは、新しく作成されたオブジェクトに対してサービスで生成された id を、アプリケーションが応答で取得する可能性が想定されるためです。Note that for creation operations, this might not be appropriate because your application may expect to get the service generated id for the newly created object in the response.

変更履歴の記録: デルタ クエリと webhook 通知Track changes: delta query and webhook notifications

アプリケーションでデータへの変更を認識する必要がある場合、対象データが変更されるたびに webhook 通知を取得できます。If your application needs to know about changes to data, you can get a webhook notification whenever data of interest has changed. この方が、定期的にポーリングするよりも効率的です。This is more efficient than simply polling on a regular basis.

データが変更されたときにプッシュ通知を取得するには、webhook 通知を使用します。Use webhook notifications to get push notifications when data changes.

アプリケーションで Microsoft Graph データをローカルにキャッシュまたは保存し、そのデータを常に最新の状態に保ったり、何らかの理由でデータへの変更履歴を記録したりする必要がある場合は、デルタ クエリを使用する必要があります。If your application is required to cache or store Microsoft Graph data locally, and keep that data up to date, or track changes to data for any other reasons, you should use delta query. これにより、アプリケーションが既に持っているデータを取得するために過剰な計算を行う必要がなくなり、ネットワーク トラフィックを最小化し、スロットルのしきい値に到達しにくくできます。This will avoid excessive computation by your application to retrieve data your application already has, minimize network traffic, and reduce the likelihood of reaching a throttling threshold.

効率よくデータを最新の状態に保つには、デルタ クエリを使用します。Use delta query to efficiently keep data up to date.

webhook とデルタ クエリを組み合わせて使用するUsing webhooks and delta query together

多くの場合、webhook とデルタ クエリを組み合わせて使用する方がさらに優れています。デルタ クエリのみを使用する場合、適切なポーリング間隔を見つける必要がありますが、間隔が短すぎると空の応答が返されてリソースが浪費され、逆に間隔が長すぎるとデータが古くなりすぎる可能性があります。Webhooks and delta query are often used better together, because if you use delta query alone, you need to figure out the right polling interval - too short and this might lead to empty responses which wastes resources, too long and you might end up with stale data. webhook 通知をデルタ クエリ呼び出しを実行するトリガーとして使うと、最適な結果が得られます。If you use webhook notifications as the trigger to make delta query calls, you get the best of both worlds.

webhook 通知を、デルタ クエリ呼び出しを実行するトリガーとして使用します。Use webhook notifications as the trigger to make delta query calls. 通知がトリガーされない場合に備えて、バックストップ ポーリングしきい値をアプリケーションに指定しておく必要もあります。You should also ensure that your application has a backstop polling threshold, in case no notifications are triggered.

バッチ処理Batching

JSON のバッチ処理を使用すると、複数の要求を単一の JSON オブジェクトに統合することにより、アプリケーションを最適化することができます。JSON batching allows you to optimize your application by combining multiple requests into a single JSON object. それぞれの要求を 1 つのバッチ要求にまとめることで、アプリケーションのネットワーク待機時間を大きく削減し、接続リソースを節約することができます。Combining individual requests into a single batch request can save the application significant network latency and can conserve connection resources.

大幅なネットワーク待機時間がパフォーマンスに大きな影響を及ぼす可能性がある場合、バッチ処理を使用します。Use batching where significant network latency can have a big impact on the performance.

信頼性とサポートReliability and support

アプリケーションの信頼性を確保しサポートを容易にするには、次のようにします。To ensure reliability and facilitate support for your application:

  • DNS TTL を優先し、接続 TTL をそれに合わせて設定します。Honor DNS TTL and set connection TTL to match it. これにより、フェールオーバーの際の可用性を確保できます。This ensures availability in case of failovers.
  • アドバタイズされたすべての DNS 応答に対して接続を開きます。Open connections to all advertised DNS answers.
  • 一意の GUID を生成し、Microsoft Graph Rest 要求ごとに送信します。Generate a unique GUID and send it on each Microsoft Graph REST request. ユーザーが Microsoft Graph に関する問題を報告する必要がある場合、このようにすると、Microsoft はエラーを容易に調査できるようになります。This will help Microsoft investigate any errors more easily if you need to report an issue with Microsoft Graph.
    • Microsoft Graph への要求ごとに一意の GUID が生成され、その GUID は client-request-id HTTP 要求ヘッダー内に送信され、アプリケーションのログにも記録されます。On every request to Microsoft Graph, generate a unique GUID, send it in the client-request-id HTTP request header, and also log it in your application's logs.
    • HTTP 応答ヘッダーからの request-idtimestamp、および x-ms-ags-diagnostic は、常に記録されます。Always log the request-id, timestamp and x-ms-ags-diagnostic from the HTTP response headers. これらは、client-request-id と共に、Stack Overflow または Microsoft サポートに問題を報告する際に必要です。These, together with the client-request-id, are required when reporting issues in Stack Overflow or to Microsoft Support.