ドライブの変更履歴を記録する

このメソッドを使用すると、ドライブおよびその子への変更履歴を時間の経過とともにアプリで記録できます。

アプリはまず、パラメーターを指定せずに delta を呼び出します。 サービスは、ドライブの階層の列挙を開始し、以下で説明するように、項目のページと @odata.nextLink 、 または のいずれかを @odata.deltaLink返します。 返された応答が表示されなくなるか、空の変更セットを含む応答が表示@odata.nextLinkされるまで、アプリは を 使用して呼び出し@odata.nextLinkを続ける必要があります。

すべての変更を受信したら、それをローカルの状態に適用できます。 今後の変更を確認するには、前回の応答の delta を使ってもう一度 @odata.deltaLink を呼び出します。

削除されたアイテムは deleted ファセット付きで返されます。 このプロパティ セットを持つアイテムは、ローカル状態から削除する必要があります。

注: すべての変更を同期した後にフォルダーが空の場合にのみ、ローカルでそのフォルダーを削除する必要があります。

アクセス許可

この API を呼び出すには、次のいずれかのアクセス許可が必要です。 アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。

アクセス許可の種類	アクセス許可 (特権の小さいものから大きいものへ)
委任 (職場または学校のアカウント)	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All
委任 (個人用 Microsoft アカウント)	Files.Read、Files.ReadWrite、Files.Read.All、Files.ReadWrite.All
アプリケーション	Files.Read.All、Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All

HTTP 要求

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

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

このメソッドは、応答を $selectカスタマイズするために、、 $expand、および $topOData クエリ パラメーター をサポートします。

パラメーター

名前	値	説明
token	string	省略可能。 指定しない場合、階層の現在の状態を列挙します。 latest の場合、最後のデルタ トークンを使用して、空の応答本文を返します。 一つ前のデルタ トークンの場合は、そのトークン以降の新しい状態を返します。

応答

成功した場合、このメソッドは応答本文で 200 OK 応答コードと、DriveItem リソースのコレクションを返します。

DriveItem のコレクションのほか、応答には次のプロパティのいずれかも含まれます。

名前	値	説明
@odata.nextLink	url	現在のセットに追加の変更がある場合に、次の使用可能な変更ページを取得するための URL です。
@odata.deltaLink	url	現在のすべての変更が返された後に、@odata.nextLink の代わりに返される URL です。 今後の次の一連の変更を読み取るために使用されます。

例 (最初の要求)

ここでは、ローカルの状態を確立するために、この API を呼び出す方法の例です。

要求

以下は最初の要求の例です。

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

応答

以下は、応答の例です。

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)"
}

この応答には変更の最初のページが含まれており、@odata.nextLink プロパティは、現在のアイテムのセットで使用可能なアイテムがさらにあることを示しています。 アプリは、アイテムのすべてのページが取得されるまで、@odata.nextLink の URL の値を要求し続ける必要があります。

例 (セットの最後のページ)

以下に、ローカルの状態を更新するためにこの API を呼び出す方法の例を示します。

要求

以下は最初の要求後の要求の例です。

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

応答

以下は、応答の例です。

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')"
}

この応答は、folder2 という名前のアイテムが削除され、アイテム file.txt は最初の要求とローカルの状態を更新する今回の要求の間で追加または変更されたことを示しています。

アイテムの最後のページには @odata.deltaLink プロパティが含まれます。このプロパティは現在のアイテム セット以降の変更を後で取得するために使用される URL を提供します。

指定したトークンの変更リストを、サービスが提供できない場合があります (長時間にわたって切断された後に、クライアントが古いトークンを再利用する場合や、サーバーの状態が変更され、新しいトークンが必要な場合など)。 このような場合、サービスは次のエラー コードのいずれかを含むエラー応答で HTTP 410 Gone エラーを返し、また、新しい差分の列挙を最初から開始する新しい nextLink を含む Location ヘッダーを返します。 完全な列挙処理が終了したら、返されたアイテムとローカルの状態を比較して、次の指示に従います。

エラーの種類	手順
resyncChangesApplyDifferences	最後に同期したときに、サービスがローカルの変更に対して最新の状態であったことが確実な場合、すべてのローカル アイテムをサーバーのバージョンと置き換えます (削除を含む)。 サーバーが把握していないすべてのローカル変更をアップロードします。
resyncChangesUploadDifferences	サービスが返さないすべてのローカル アイテムをアップロードして、サーバーのバージョンと異なるすべてのファイルをアップロードします (どちらがより最新の状態であるかわからない場合は、両方のコピーを保持する)。

現在の deltaLink を取得する

シナリオによっては、ドライブにすでにあるすべてのアイテムを最初に列挙する代わりに、現在の deltaLink 値を要求すると便利な場合があります。

これは、アプリで変更についてのみ知る必要があり、既存のアイテムは知る必要がない場合に役立ちます。 最新の deltaLink を取得するには、クエリ文字列パラメーター ?token=latest を指定して delta を呼び出します。

注: フォルダーまたはドライブ内のアイテムの完全なローカル表現を維持しようとしている場合は、最初の列挙に delta を使用する必要があります。 その他の方法 (フォルダーの children コレクションをページングするなど) は、列挙時に書き込みが発生した場合に、すべてのアイテムを 1 つ残らず返す保証がありません。 delta の使用は、必要とするデータのすべてを読み取ったことを保証する唯一の方法です。

要求

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

応答

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

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

注釈

• 差分フィードは各変更を示すのではなく、各アイテムの最新の状態を示すものです。 アイテムの名前が 2 回変更された場合、最新の名前で 1 回だけ表示されます。

• 差分フィードには、さまざまな理由から同じアイテムが複数回表示される場合があります。 その場合は最後に出現したものを使用する必要があります。

• parentReference項目の プロパティには、パスの値は含まれません。 これは、フォルダーの名前を変更しても、フォルダーの子孫がデルタから返されないために発生 します。 デルタを使用する場合は、常に ID で項目を追跡する必要があります。

• ドライブに追加された共有フォルダーについて、デルタは、共有フォルダー内の変更に関する情報を返しません。 代わりに、共有フォルダー自体を対象とする、別のデルタの呼び出しが行われます。

• デルタには、OneDrive for Business に対する追加の制約があります。詳細については、「リリース ノート」を参照してください。

エラー応答

前述した再同期エラーの詳細に加えて、エラーがどのように返されるかについては、「エラー応答」を参照してください。