ドライブの変更履歴を記録するTrack changes for a Drive

このメソッドでは、アプリがドライブおよびその子への変更履歴を時間の経過とともに記録できます。This method allows your app to track changes to a drive and its children over time.

アプリはまず、パラメーターを指定せずに delta を呼び出します。サービスはドライブの階層の列挙を開始し、次に説明するように、アイテムのページと @odata.nextLink または @odata.deltaLink のいずれかを返します。@odata.nextLink が返されなくなるまで、または変更の空のセットが応答で返されるまで、アプリは @odata.nextLink を使って呼び出しを続けます。Your app begins by calling delta without any parameters. The service starts enumerating the drive's hierarchy, returning pages of items and either an @odata.nextLink or an @odata.deltaLink, as described below. Your app should continue calling with the @odata.nextLink until you no longer see an @odata.nextLink returned, or you see a response with an empty set of changes.

すべての変更を受信したら、それをローカルの状態に適用できます。今後の変更を確認するには、前回の応答の @odata.deltaLink を使ってもう一度 delta を呼び出します。After you have finished receiving all the changes, you may apply them to your local state. To check for changes in the future, call delta again with the @odata.deltaLink from the previous response.

削除されたアイテムは deleted ファセット付きで返されます。このプロパティ セットを持つアイテムは、ローカル状態から削除する必要があります。Deleted items are returned with the deleted facet. Items with this property set should be removed from your local state.

注: すべての変更を同期した後にフォルダーが空の場合にのみ、ローカルでそのフォルダーを削除する必要があります。Note: you should only delete a folder locally if it is empty after syncing all the changes.

アクセス許可Permissions

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

アクセス許可の種類Permission type アクセス許可 (特権の小さいものから大きいものへ)Permissions (from least to most privileged)
委任 (職場または学校のアカウント)Delegated (work or school account) Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.AllFiles.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
委任 (個人用 Microsoft アカウント)Delegated (personal Microsoft account) Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.AllFiles.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All
アプリケーションApplication Files.Read.All、Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.AllFiles.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

HTTP 要求HTTP request

GET /drives/{drive-id}/root/delta
GET /groups/{groupId}/drive/root/delta
GET /me/drive/root/delta
GET /sites/{siteId}/drive/root/delta
GET /users/{userId}/drive/root/delta

関数パラメーターFunction parameters

パラメーターParameter Type 説明Description
tokentoken stringstring 省略可能。Optional. 指定しない場合、階層の現在の状態を列挙します。If unspecified, enumerates the hierarchy's current state. latest の場合、最後のデルタ トークンを使用して、空の応答本文を返します。If latest, returns empty response with latest delta token. 一つ前のデルタ トークンの場合は、そのトークン以降の新しい状態を返します。If a previous delta token, returns new state since that token.

オプションのクエリ パラメーターOptional query parameters

このメソッドは、応答をカスタマイズするための $select$expand$topOData クエリ パラメーターをサポートします。This method supports the $select, $expand, and $top OData query parameters to customize the response.

応答Response

成功した場合、このメソッドは応答本文で 200 OK 応答コードと、DriveItem リソースのコレクションを返します。If successful, this method returns a 200 OK response code and a collection of DriveItem resources in the response body.

DriveItem のコレクションのほか、応答には次のプロパティのいずれかも含まれます。In addition to the collection of DriveItems, the response will also include one of the following properties:

名前Name Value 説明Description
@odata.nextLink**@odata.nextLink** urlurl 現在のセットに追加の変更がある場合に、次の使用可能な変更ページを取得するための URL です。A URL to retrieve the next available page of changes, if there are additional changes in the current set.
@odata.deltaLink**@odata.deltaLink** urlurl 現在のすべての変更が返された後に、**@odata.nextLink** の代わりに返される URL です。今後の次の一連の変更を読み取るために使用されます。A URL returned instead of **@odata.nextLink** after all current changes have been returned. Used to read the next set of changes in the future.

例 (最初の要求)Example (Initial Request)

ここでは、ローカルの状態を確立するために、この API を呼び出す方法の例です。Here is an example of how to call this API to establish your local state.

要求Request

以下は最初の要求の例です。Here is an example of the initial request.

GET https://graph.microsoft.com/v1.0/me/drive/root/delta

応答Response

以下は、応答の例です。Here is an example of the response.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "id": "0123456789abc",
            "name": "folder2",
            "folder": { }
        },
        {
            "id": "123010204abac",
            "name": "file.txt",
            "file": { }
        },
        {
            "id": "2353010204ddgg",
            "name": "file5.txt",
            "deleted": { }
        }
    ],
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/drive/delta(token=1230919asd190410jlka)"
}

SDK サンプル コードSDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Me.Drive.Root.Delta()
    .Request()
    .GetAsync();

SDK をプロジェクトに追加し、 authproviderインスタンスを作成する方法の詳細については、 sdk のドキュメントを参照してください。Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

この応答には変更の最初のページが含まれており、@odata.nextLink** プロパティは、現在のアイテムのセットで使用可能なアイテムがさらにあることを示しています。アプリは、アイテムのすべてのページが取得されるまで、@odata.nextLink** の URL の値を要求し続ける必要があります。This response includes the first page of changes, and the **@odata.nextLink** property indicates that there are more items available in the current set of items. Your app should continue to request the URL value of **@odata.nextLink** until all pages of items have been retrieved.

例 (セットの最後のページ)Example (Last page in a set)

以下に、ローカルの状態を更新するためにこの API を呼び出す方法の例を示します。Here is an example of how to call this API to update your local state.

要求Request

以下は最初の要求後の要求の例です。Here is an example request after the initial request.

GET https://graph.microsoft.com/v1.0/me/drive/root/delta(token='1230919asd190410jlka')

応答Response

以下は、応答の例です。Here is an example of the response.

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "id": "0123456789abc",
            "name": "folder2",
            "folder": { },
            "deleted": { }
        },
        {
            "id": "123010204abac",
            "name": "file.txt",
            "file": { }
        }
    ],
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?(token='1230919asd190410jlka')"
}

SDK サンプル コードSDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Me.Drive.Root.Delta('1230919asd190410jlka')
    .Request()
    .GetAsync();

SDK をプロジェクトに追加し、 authproviderインスタンスを作成する方法の詳細については、 sdk のドキュメントを参照してください。Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

この応答は、folder2 という名前のアイテムが削除され、アイテム file.txt は最初の要求とローカルの状態を更新する今回の要求の間で追加または変更されたことを示しています。This response indicates that the item named folder2 was deleted and the item file.txt was either added or modified between the initial request and this request to update the local state.

アイテムの最後のページには **@odata.deltaLink** プロパティが含まれます。このプロパティは現在のアイテム セット以降の変更を後で取得するために使用される URL を提供します。The final page of items will include the **@odata.deltaLink** property, which provides the URL that can be used later to retrieve changes since the current set of items.

指定したトークンの変更リストを、サービスが提供できない場合があります (長時間にわたって切断された後に、クライアントが古いトークンを再利用する場合や、サーバーの状態が変更され、新しいトークンが必要な場合など)。このような場合、サービスは次のエラー コードのいずれかを含むエラー応答で HTTP 410 Gone エラーを返し、また、新しい差分の列挙を最初から開始する新しい nextLink を含む Location ヘッダーを返します。完全な列挙処理が終了したら、返されたアイテムとローカルの状態を比較して、次の指示に従います。There may be cases when the service can't provide a list of changes for a given token (for example, if a client tries to reuse an old token after being disconnected for a long time, or if server state has changed and a new token is required). In these cases the service will return an HTTP 410 Gone error with an error response containing one of the error codes below, and a Location header containing a new nextLink that starts a fresh delta enumeration from scratch. After finishing the full enumeration, compare the returned items with your local state and follow these instructions.

エラーの種類Error Type 手順Instructions
resyncChangesApplyDifferences 最後に同期したときに、サービスがローカルの変更に対して最新の状態であったことが確実な場合、すべてのローカル アイテムをサーバーのバージョンと置き換えます (削除を含む)。サーバーが把握していないすべてのローカル変更をアップロードします。Replace any local items with the server's version (including deletes) if you're sure that the service was up to date with your local changes when you last sync'd. Upload any local changes that the server doesn't know about.
resyncChangesUploadDifferences サービスが返さないすべてのローカル アイテムをアップロードして、サーバーのバージョンと異なるすべてのファイルをアップロードします (どちらがより最新の状態であるかわからない場合は、両方のコピーを保持する)。Upload any local items that the service did not return, and upload any files that differ from the server's version (keeping both copies if you're not sure which one is more up-to-date).

シナリオによっては、ドライブにすでにあるすべてのアイテムを最初に列挙する代わりに、現在の deltaLink 値を要求すると便利な場合があります。In some scenarios, it may be useful to request the current deltaLink value without first enumerating all of the items in the drive already.

これは、アプリで変更についてのみ知る必要があり、既存のアイテムは知る必要がない場合に役立ちます。This can be useful if your app only wants to know about changes, and doesn't need to know about existing items. 最新の deltaLink を取得するには、クエリ文字列パラメーター ?token=latest を指定して delta を呼び出します。To retrieve the latest deltaLink, call delta with a query string parameter ?token=latest.

注: フォルダーまたはドライブ内のアイテムの完全なローカル表現を維持しようとしている場合は、最初の列挙に delta を使用する必要があります。その他の方法 (フォルダーの children コレクションをページングするなど) は、列挙時に書き込みが発生した場合に、すべてのアイテムを 1 つ残らず返す保証がありません。delta の使用は、必要とするデータのすべてを読み取ったことを保証する唯一の方法です。Note: If you are trying to maintain a full local representation of the items in a folder or a drive, you must use delta for the initial enumeration. Other approaches, such as paging through the children collection of a folder, are not guaranteed to return every single item if any writes take place during the enumeration. Using delta is the only way to guarantee that you've read all of the data you need to.

要求Request

GET /me/drive/root/delta?token=latest

応答Response

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [ ],
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?token=1230919asd190410jlka"
}

SDK サンプル コードSDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var queryOptions = new List<QueryOption>()
{
    new QueryOption("token", "latest")
};

var delta = await graphClient.Me.Drive.Root.Delta()
    .Request( queryOptions )
    .GetAsync();

SDK をプロジェクトに追加し、 authproviderインスタンスを作成する方法の詳細については、 sdk のドキュメントを参照してください。Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

注釈Remarks

  • 差分フィードは各変更を示すのではなく、各アイテムの最新の状態を示すものです。アイテムの名前が 2 回変更された場合、最新の名前で 1 回だけ表示されます。The delta feed shows the latest state for each item, not each change. If an item were renamed twice, it would only show up once, with its latest name.

  • 差分フィードには、さまざまな理由から同じアイテムが複数回表示される場合があります。その場合は最後に出現したものを使用する必要があります。The same item may appear more than once in a delta feed, for various reasons. You should use the last occurrence you see.

  • アイテムの parentReference プロパティにはパスの値は含まれません。これは、フォルダー名を変更してもデルタからそのフォルダーの子孫が返されることはないためです。差分を使用する場合、アイテムは必ず ID で追跡する必要がありますThe parentReference property on items will not include a value for path. This occurs because renaming a folder does not result in any descendants of the folder being returned from delta. When using delta you should always track items by id.

  • OneDrive for Business および SharePoint では、deltaroot フォルダーでのみサポートされ、ドライブ内の他のフォルダーではサポートされません。In OneDrive for Business and SharePoint, delta is only supported on the root folder, not on other folders within a drive.

  • デルタ クエリは、次の表に示す通り、操作とサービスの種類によって、一部の DriveItem プロパティを返しません。Delta query will not return some DriveItem properties, depending on the operation and service type, as shown in the following tables.

    OneDrive for BusinessOneDrive for Business

    操作の種類Operation type デルタ クエリに省略されるプロパティProperties omitted by delta query
    作成/変更Create/Modify ctag, lastModifiedByctag, lastModifiedBy
    削除Delete ctag, lastModifiedBy, name

    OneDrive (コンシューマー向け)OneDrive (consumer)

    操作の種類Operation type デルタ クエリに省略されるプロパティProperties omitted by delta query
    作成/変更Create/Modify 該当なしn/a
    削除Delete ctag, size

エラー応答Error responses

前述した再同期エラーの詳細に加えて、エラーがどのように返されるかについては、「エラー応答」を参照してください。In addition to the resync errors detailed above, see Error Responses for details about how errors are returned.