大規模のファイル検出および変更検出のベスト プラクティスBest practices for discovering files and detecting changes at scale

SharePoint および OneDrive ストア数百万のファイル。SharePoint and OneDrive store millions of files. すべてのファイルおよび変更をスケールで理解しようとするときは、適切な呼び出しパターンを使用することが重要です。It is critical to use the right calling patterns when trying to understand all files and changes at scale. 従来、アトミックレベルでファイルにアクセスするための Api は多数あります。Historically, there are many APIs to access files at an atomic level. これらの Api の多くは大規模では効率的ではありませんが、1人のユーザーの操作に対して適切に動作します。Many of these APIs are not efficient at a large scale but work well for a single user interaction. このガイダンスでは、アプリケーションが Office 365 と統合されるように Office 365 テナントまたは OneDrive を監視する方法について説明します。これにより、最大限のパフォーマンスと効率が実現されます。This guidance walks through how to monitor an Office 365 tenant or OneDrive so that your application integrates with Office 365 with maximum performance and efficiency. 通常、この種の必要があるアプリケーションには、同期エンジン、バックアッププロバイダ、検索インデクサー、分類エンジン、データ損失防止プロバイダーがあります。Applications that typically have this type of need are sync engines, backup providers, search indexers, classification engines, and data loss prevention providers.

適切なアクセス許可の取得Getting the right permissions

ユーザーとの信頼関係を構築するには、アプリを機能させるために必要な最小限の[アクセス許可スコープ][]の適切なセットを使用することが重要です。To build trust with users it is important to use the correct minimal set of permission scopes needed for an app to function. ほとんどのスキャンアプリケーションは、アプリケーションのアクセス許可を使用して操作する必要があります。これは、アプリケーションが特定のユーザーとは独立して実行されていることを示します。Most scanning applications will want to operate with Application permissions, this indicates your application is running independently of any particular user. ファイルにアクセスするには、ファイルを要求する必要があります。すべてのスコープまたはすべてのスコープを取得します。To access files you should request either the Files.Read.All or Files.ReadWrite.All scope. すべてのサイトコレクションのリストを含むSharePoint リソースにアクセスする場合は、すべてのサイトコレクションが該当します。For access to SharePoint resources, including the list of all site collections, Sites.Read.All or Sites.ReadWrite.All is appropriate. 権限を正しく処理するためには、 FullControlを要求する必要もあります。In order to process permissions correctly you will also need to request Sites.FullControl.All.

承認の種類、アクセス許可のスコープ、およびユーザーAuthorization types, permission scopes and users

Microsoft Azure でアプリケーションのアクセス許可を構成するときは、アプリケーションのアクセス許可と委任されたアクセス許可のどちらかを選択できます。When you configure an application's permissions in Microsoft Azure you can choose between Application permissions and Delegated permissions. 前述したように、ほとんどのスキャンアプリケーションでは、アプリケーションのアクセス許可が必要になります。As noted above most scanning applications will want Application permissions. 委任されたアクセス許可では、アプリケーションが、グローバルではなく、サインインしているユーザーのコンテキストで動作する必要があります。Delegated permissions require your application to operate in the context of a signed in user rather than globally. 委任されたモデルでは、現在のユーザーがアクセスできるコンテンツに制限されます。In the delegated model you are restricted to content that the current user has access to.

アクセス許可の重要な側面の1つとして、管理者が委任されたアクセス許可ではなくアプリケーションを要求するアプリケーションにアクセス許可を付与すると、アクセス許可の付与がユーザーではなくテナントとアプリケーションに関連付けられるということです。One important aspect of permissions to note is that when an administrator grants permissions to an application requesting Application rather than Delegated permissions the permission grant is being associated with the tenant and application rather than the user. アクセス許可によってアクセス権が付与されている必要がありますが、アプリケーションが要求するリソーススコープへのアクセス権を超えて、アプリケーションに対する特別な管理権限を割り当てることはありません。Although it requires and administrator to grant the access the access grant does not confer any special administrative permissions to the application beyond access to the resource scopes requested by the application.

SharePoint と OneDrive から大量のデータを処理するアプリケーションでは、次のような一貫した呼び出しパターンに従う必要があります。For applications that process large amounts of data from SharePoint and OneDrive, you should follow a consistent calling pattern like the following.

  1. Discover –スキャンする場所を構成します。Discover – Configure the locations that you want to scan.
  2. クロール–必要なファイルのセット全体を検出して処理します。Crawl – Discover and process the entire set of files that you are interested in.
  3. Notify –通知によってこれらのファイルに対する変更を監視します。Notify – Monitor changes to those files via notification.
  4. 変更の処理: デルタクエリを使用して変更されたファイルのみを再処理します。Process changes – Reprocess only files that have changed by using delta query.

パターンは、次の図のようになります。The pattern will look like the following diagram. この記事では、実装の各手順について詳細に説明します。This article goes into detail on each step for implementation.

Microsoft Graph とクライアントアプリケーションの間の通話フローのスキャン

これらの各要素には、Microsoft Graph API と既存の SharePoint Api でそれらを実現するためのメカニズムがいくつかあります。Each of these elements may have several mechanisms to accomplish them in the Microsoft Graph API and existing SharePoint APIs. この記事の目的は、各タスクを完了するための最適な方法を提供することです。The goal of this article is to give you the best way available today to complete each task.

スキャンする場所を検出するDiscover locations to scan

アプリケーションがスキャンする場所を構成することは、今日の手動のプロセスです。Configuring the locations that you want your application to scan is a manual process today. 多くの場合、この手順には、ユーザー向けのアプリケーション環境を提供する必要があります。この機能を公開する方法と、すべてのユーザーに公開するか、管理者のみが自分の権限を持つか。In many cases, you will want to provide a user-facing application experience for this step; how you expose this capability and whether it is exposed to all users or just administrators is up to you. スキャンするユーザーの OneDrives と SharePoint サイトコレクションおよびサブサイトを特定する必要があります。You will want to determine which users’ OneDrives and which SharePoint site collections and subsites you are scanning.

各ユーザーの OneDrive には、監視できる[ドライブ][]が1つ含まれています。Each user’s OneDrive contains a single drive that you can monitor. SharePoint サイトコレクションとサブサイトには、サイト内のドキュメントライブラリごとに1つずつ、複数のドライブが存在する場合があります。SharePoint site collections and subsites may have multiple drives, one for each document library in the site. /Drive エンドポイントを使用して、サイト内の各ドライブを検出できます。You can discover each drive in a site by using the /drives endpoint. たとえば、テナントのルートサイトのすべてのドライブを取得するには、次のように使用します。For example, to get all drives in the root site of the tenant you can use:

https://graph.microsoft.com/v1.0/sites/root/drives

ドライブは大規模ファイルアクティビティの開始点です。The drive is the starting point for large-scale file activities. これらのドライブを使用して、ファイルの完全なリストを取得し、通知用の webhook を接続し、デルタクエリを使用して、ドライブ内の項目に加えられた変更のセットを取得します。You’ll use these drives to get complete lists of files, connect webhooks for notifications, and use delta query to get sets of changes to items in the drives.

SharePoint サイトコレクションと OneDrive for Business ドライブを見つける方法How to find SharePoint site collections and OneDrive for Business drives

アプリケーションのアクセス許可で Microsoft Graph を使用すると、OneDrive for Business ドライブを含むサイトを含む、サイトコレクションの完全なリストを取得できます。Using Microsoft Graph with Application permissions, you can obtain the full list of site collections, including sites containing OneDrive for Business drives. このリストを取得するには、次の API 呼び出しを使用します。To get this list use the following API call:

GET /sites

サイト列挙 API は、サイト構造に対して作成または変更された新しいサイトに関する情報を取得するデルタクエリもサポートします。The sites enumeration API also supports the delta query to get information about new sites created or changes to site structure. サイト列挙のデルタクエリサポートは、現在 Microsoft Graph ベータ版に展開されています。Delta query support for site enumeration is currently rolling out to the Microsoft Graph Beta version. デルタクエリの詳細については、「」を参照してください。Please keep reading for more information about delta query.

新しいサイトコレクションに関する通知を受信するには、Microsoft Graph の[サブスクリプション][]エンドポイントを使用して web フックにサブスクライブできます。To receive notifications about new site collections you can subscribe to web hooks using the Microsoft Graph subscriptions endpoint. これらの通知のターゲットリソースは、 /サイトです。The target resource for these notifications is /sites. 新しいサイトコレクションが作成または削除されたとき、またはサブサイトやリストが作成されたときに通知を受け取ります。You will receive notifications when new site collections are created or deleted as well as when sub sites or lists are created.

デルタクエリを使用したクロールと処理Crawl and process by using delta query

ドライブ内のファイルの初期リストを取得するには、パラメーターを使用せずに、1つのデルタクエリ呼び出しを行います。To get the initial list of files in a drive, make a single delta query call with no parameters. デルタクエリは、すべてのコンテンツの最初のクロールをアプリに提供し、その後、特定の時点から変更を加えます。The delta query gives apps an initial crawl of all content and then subsequent changes from a point in time. デルタクエリは、呼び出されるたびに、今後の変更を取得するために必要なリンクを返します。The delta query returns the link necessary to get future changes each time it is called.

たとえば、SharePoint サイトの既定のドキュメントライブラリにあるすべてのファイルを取得する場合は、次のクエリを使用できます。For example, if you wanted to get all the files in the default document library in a SharePoint site, you could use this query:

/sites/{siteId}/drive/root/delta

この API は、ドライブ内のすべてのファイルを表す結果のページを返します。This API returns pages of results that represent all the files in the drive. 返された @odata リンクを使用してファイルのすべてのページを取得した後、@odata 返された deltaLink を使用してデルタクエリを再度実行し、最後にデルタクエリを呼び出した後に変更を取得できます。After you’ve retrieved all the pages of files by using the returned @odata.nextLink, you can make the delta query again with the returned @odata.deltaLink to get changes since the last time you called delta query. 後で変更を効率的にチェックできるように、deltaLink によって返される URL を常に保持し @odata ておくようにしてください。Always remember to keep the URL returned by @odata.deltaLink so you can efficiently check for the changes later on.

デルタクエリによって返されるリンクは、次のようになります。The links returned by the delta query will look like this:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(driveItem)",
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?$select=*%2csharepointIds&token=MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM2NzExNzY2MzIxMDcwMDAwOzE5ODAzMzU5ODslMjM7JTIzOyUyMzQ",
    "value": [
        {
            "@odata.type": "#microsoft.graph.driveItem",
            "createdDateTime": "2017-07-27T02:41:36Z",
…
}

詳細なサンプルについては、デルタクエリの[ドキュメント][]を参照してください。For a more detailed sample, see the delta query documentation.

デルタクエリは、[ドライブ項目][]の配列を返します。Delta query returns an array of driveItems. 特定の情報が必要であることが事前にわかっている場合は、デルタクエリを使用して select ステートメントに含めることができます。If you know ahead of time that you want specific information, you can include it on a select statement with the delta query. また、必要に応じて、特定の Drive アイテムの要求を使用してデルタ呼び出しをフォローアップすることもできます。You can additionally follow up the delta call with a request for a specific driveItem should you need it. デルタクエリを使用すると、変更に対してクエリを実行する必要があるアイテムの数を絞り込んで、アプリケーションの効率を向上させることができます。Delta query will still help narrow down the number of items you have to query against for changes, making your application more efficient.

Webhook を使用して変更の通知を受け取るGet notified of changes by using webhooks

ドライブ上で発生する変更についてデルタクエリを最大限に活用するには、いつ復帰して変更を確認する必要があるかを知るための効果的な戦略が必要です。To make best use of the delta query for changes happening on a drive, you need an effective strategy to know when to come back and ask for the changes. 以前は、一定の間隔で OneDrive と SharePoint をポーリングして変更を列挙するようにアプリを作成しているかもしれません。In the past, you may have written your app to poll OneDrive and SharePoint at some fixed interval and enumerated the changes yourself. デルタクエリを使用すると、列挙パーツが実行されるので、いつ復帰する必要があるかを知るだけで済みます。With delta query, the enumeration part is done for you, so you just need to know when to come back. Webhooks を使用すると、サービスのポーリングを避けることができます。その代わりに、関心のある変更があったときに通知を受け取ることができます。Webhooks allow you to avoid polling the service, and instead receive a notification when something has changed that you’re interested in. サービスを繰り返しポーリングしたり、高い頻度でポーリングしたりすると、アプリが過剰な呼び出しパターンによって制限されます。Polling the service repeatedly or at high rates causes your app to be throttled due to excessive calling patterns.

Webhooks は、サブスクリプション API for Microsoft Graph を使用して接続されます。Webhooks are attached by using the subscriptions API for Microsoft Graph. Microsoft graph の webhook とサブスクリプション API の詳細については、 microsoft graph サイトのドキュメントを参照してください。You can find the full documentation for Microsoft Graph webhooks and the Subscriptions API on the Microsoft Graph site.

特定のリソース (この場合はドライブ) に関連付けられたサブスクリプションを作成する必要があります。You will need to create a subscription that is associated with a specific resource (in this case a drive). ドライブは、webhooks の "update" 変更の種類をサポートしています。Drives support the “update” change type for webhooks. "Update" は、ドライブ内のコンテンツが変更されたこと、または新しいコンテンツが追加または削除されたことを示します。An “update” indicates that content within the drive has changed or that new content has been added or deleted. Webhook サブスクリプションには、定期的に更新する必要がある関連するタイムアウトがあります。Webhook subscriptions have an associated timeout that needs to be periodically refreshed. サブスクリプションを更新する方法については、前に説明したドキュメントを参照してください。See the earlier-mentioned documentation on how to refresh your subscriptions. Webhook をサブスクライブした直後に、最終変更トークンでデルタクエリを使用することをお勧めします。これは、最初のクロールと webhook の設定の間に発生した変更を見逃さないようにするためです。We recommend using delta query with your last change token immediately after you subscribe to webhooks to ensure that you don’t miss any changes that happened between initial crawl and setting up your webhooks.

Webhook を使用してアプリケーション通知を送信する場合でも、定期的なデルタクエリを提供して、通知を受信してから長い時間が経過しても変更が失われないようにすることをお勧めします。Even with webhooks sending your application notifications, you may want to provide a periodic delta query to ensure that no changes are missed if it appears to have been a long time since a notification was received. この定期的なチェックには、1日に1回を使用することをお勧めします。We recommend no more than once per day for this periodic check. デルタクエリを使用すると、システム内の変更を簡単にキャッチして、それを見逃しないようにすることができます。The delta query still allows you to easily catch up and not miss any changes in the system.

セキュリティイベントに対する webhook 通知の受信Receiving webhook notifications for security events

OneDrive および SharePoint は、セキュリティイベントのアプリケーション通知の送信をサポートしています。OneDrive and SharePoint support sending your application notifications of security events. これらのイベントをサブスクライブするには、webhook を登録するための要求に "優先: includesecuritywebhooks" ヘッダーを追加する必要があります。To subscribe to these events you will need to add the "prefer:includesecuritywebhooks" header to your request to register a webhook. Webhook が登録されると、アイテムのアクセス許可が変更されたときに通知を受信します。Once the webhook is registered you will receive notifications when the permissions on an item change. このヘッダーは SharePoint および OneDrive for business に適用されますが、コンシューマー OneDrive のアカウントには適用されません。This header is applicable to SharePoint and OneDrive for Business but not consumer OneDrive accounts.

プロセスの変更Process changes

アプリケーションが webhook を使用して通知を受信した後、直ちに 202-受理されたコードを Microsoft Graph に送信して、通知を確認する必要があります。After your application receives a notification through a webhook, you need to acknowledge the notification by immediately sending a 202 – Accepted code back to Microsoft Graph. 時間のかかる処理を開始する前に、このコードを送信する必要があります。You should send this code before beginning any time-consuming processing. これに失敗すると、アプリが誤通知として表示される可能性がある、追加の再試行が送信されます。Failing to do so results in additional retries being sent, which your app might view as false notifications.

最新の変更についてデルタクエリを使用して確認を行い、アプリが最新の状態になっている必要があります。Follow up the acknowledgement with a delta query for the latest changes, and your app should be up to date. 特定のドライブに大量のトラフィックパターンが想定される場合は、変更通知の後ではなく、制限された間隔でデルタクエリを呼び出すことを検討する必要があります。If you are expecting heavy traffic patterns on a particular drive, you should consider calling delta query at a reduced interval rather than after each change notification. また、deltaLink パラメーターに返される新しい値を格納して、API を再度呼び出すための新しいトークンを取得してください。Also, make sure to store the new value returned in the deltaLink parameter to get a new token for calling the API again.

処理で個々のファイルのコンテンツをダウンロードする必要がある場合は、cTag プロパティを使用して、最後にダウンロードしてからファイルの内容が変更されているかどうかを確認できます。If your processing requires downloading the contents of an individual file, you can use the cTag property to determine if the contents of the file have changed since the last time you downloaded it. ファイルをダウンロードする必要があることがわかったら、デルタクエリ応答で返されたドライブ項目の[/コンテンツ][]プロパティにアクセスできます。Once you know you want to download the file, you can access the /content property of the DriveItem returned in a delta query response.

アクセス許可の階層をスキャンするScanning permissions hierarchies

既定では、デルタクエリの応答には、親からアクセス許可を継承しているものの、直接共有の変更がない場合でも、アイテムの共有情報が含まれます。By default, the delta query response will include sharing information for items even if they inherit their permissions from their parent and did not have direct sharing changes themselves. デルタクエリの応答には、コンテンツまたはメタデータに直接変更が加えられているアイテムと、変更されたアイテムの親階層のみが含まれていることに注意してください。Note that the delta query response only includes items with direct changes to their content or metadata and the parent hierarchy of the changed items. 通常は、これにより、共有情報が変更されたアイテムだけでなく、すべてのアイテムのアクセス許可の詳細を取得するためフォローアップコールが発生します。This typically then results in a follow up call to get the permission details for every item rather than just the ones whose sharing information changed. "優先: hierarchicalsharing" ヘッダーをデルタクエリ要求に追加することによって、アクセス許可の変更がどのように行われるかについての理解を深めることができます。You can optimize your understanding of how permission changes happen by adding the "Prefer: hierarchicalsharing" header to your delta query request.

"優先: hierarchicalsharing" ヘッダーが指定されている場合は、アクセス許可階層のルートについての共有情報と、明示的に共有されている変更を明示的に保持しているアイテムが返されます。When the "Prefer: hierarchicalsharing" header is provided, sharing information will be returned for the root of the permissions hierarchy, as well as items that explicitly have sharing changes. 共有の変更によってアイテムから共有を削除する場合は、親から継承したアイテムと共有リンクを持たないアイテムを区別するための空の共有ファセットが見つかります。In cases where the sharing change is to remove sharing from an item you will find an empty sharing facet to differentiate between items that inherit from their parent and those that are unique but have no sharing links. また、この空の共有ファセットが、初期スコープを決定するために共有されていないアクセス許可階層のルートにも表示されます。You will also see this empty sharing facet on the root of a permission hierarchy that is not shared to establish the initial scope.

多くのスキャンシナリオでは、特にアクセス許可の変更に関心がある場合があります。In many scanning scenarios you may be interested specifically in changes to permissions. デルタクエリの応答で、変更されたアクセス許可が変更されたことを明確にするために、"優先: deltashowsharingchanges" ヘッダーを提供できます。To make it clear in the delta query response which changes are the result of permissions being changed you can provide the "Prefer: deltashowsharingchanges" header. このヘッダーを指定すると、アクセス許可の変更によってデルタクエリの応答に表示されるすべてのアイテムの @microsoft "True" が、Microsoft Graph に対して呼び出したときに "True" に変更されます。 SharePoint または OneDrive API を直接使用している場合、注釈は "@oneDrive 変更済み": "True" になります。When this header is provided all items that appear in the delta query response due to permission changes will have the "@microsoft.graph.sharedChanged":"True" OData annotation present when calling against Microsoft Graph, when using the SharePoint or OneDrive API directly the annotation will be "@oneDrive.sharedChanged":"True". セキュリティの webhooks と同様に、この機能は SharePoint および OneDrive for business にも適用されますが、コンシューマー OneDrive のアカウントでは利用できません。Like the security webhooks, this feature is applicable to SharePoint and OneDrive for Business but not consumer OneDrive accounts.

スロットルが表示された場合はどうなりますか?What happens when you get throttled?

一部のシナリオでは、アプリケーションが Microsoft Graph から429または503応答を取得することがあります。In some scenarios, your application may get a 429 or 503 response from Microsoft Graph. これは、要求が現在調整中であることを示します。This indicates that your request is currently being throttled. SharePoint では、各顧客テナントでのアプリケーションの使用に基づいてアプリケーションが調整されることに注意してください。One thing to keep in mind is that SharePoint throttles applications based on an application's use with each customer tenant. テナント内の1つのリソースに対して要求を行うと、その同じテナントに対して別のリソースを呼び出すためのリソースが減少します。Serving a request for one resource in a tenant will correspondingly give you less resources to make a call to another resource for that same tenant. 最終的には、アプリがスロットル応答を受信するという複数の理由が考えられ、アプリがこのような状況で適切に応答することが重要です。Ultimately there could be multiple reasons why your app receives a throttle response and it is critical that your app responds correctly in these situations.

429または503応答コードの受信を回復するには、応答ヘッダーの [再試行後] フィールドに指定されている期間が経過した後に再試行してください。To recover from receiving a 429 or 503 response code, try again after waiting for the duration specified in the Retry-After field in the response header. 調整が持続する場合は、再試行後の値が時間の経過とともに長くなり、システムが回復できることがあります。If throttling persists, the Retry-After value may become longer over time, allowing the system to recover. 時間をかけた後に再試行されないアプリは、不適切な呼び出しパターンによってブロックされます。Apps that do not honor the retry after duration before calling back will be blocked due to abusive calling patterns.

429または503の回復を待機している場合は、サービスに対して行うすべての要求を一時停止する必要があります。When waiting for 429 or 503 recovery you should ensure that you pause all further requests you are making to the service. これは、マルチスレッドのシナリオでは特に重要です。This is especially important in multi-threaded scenarios. スロットル応答を受信している間に通話を追加すると、アプリが unthrottled になるまでにかかる時間が長くなります。Making additional calls while receiving throttle responses will extend the time it takes for your app to become unthrottled.

Microsoft Graph リソースが調整を使用する方法の詳細については、 [Microsoft graph の調整ガイダンス][]を参照してください。For more detailed information about how Microsoft Graph resources work with throttling, see the Microsoft Graph throttling guidance.