driveItem: delta

  • [アーティクル]

名前空間: microsoft.graph

driveItem とその子アイテムの時間経過による変化を追跡します。

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

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

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

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

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「 アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、 アクセス許可のリファレンスを参照してください。

アクセス許可の種類 最小特権アクセス許可 特権の高いアクセス許可
委任 (職場または学校のアカウント) Files.Read Files.Read.All、Files.ReadWrite、Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All
委任 (個人用 Microsoft アカウント) Files.Read Files.Read.All、Files.ReadWrite、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

関数パラメーター

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

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

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

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須です。 認証と承認の詳細については、こちらをご覧ください。

要求本文

このメソッドには、要求本文を指定しません。

応答

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

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

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

例

例 1: 最初の要求

この 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 の値を要求し続ける必要があります。

例 2: セットの最終ページ

この API を呼び出してローカル状態を更新する方法の例を次に示します。

要求

最初の要求の後の要求の例を次に示します。

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

応答

次の例は応答を示しています。

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

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

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

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

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

シナリオによっては、ドライブにすでにあるすべてのアイテムを最初に列挙する代わりに、現在の 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"
}

例 4: タイムスタンプを使用したデルタ結果の取得

一部のシナリオでは、クライアントは特定の時間までのドライブの状態を知っていても、その時点の deltaLink を持っていない場合があります。 この場合、クライアントは、クエリ文字列パラメーターのtoken値として URL エンコードされたタイムスタンプを使用してを呼び出deltaすことができます。たとえば、?token=2021-09-29T20%3A00%3A00Z'?token=2021-09-29T12%3A00%3A00%2B8%3A00' などです。

トークンの代わりにタイムスタンプを使用することは、OneDrive for Business と SharePoint でのみサポートされています。

注: クライアントは、独自のトークンを生成するのではなく、可能な限りクエリで提供される deltaLink delta を使用する必要があります。 この機能は、deltaLink がわからない場合にのみ使用するようにしてください。

要求

GET /me/drive/root/delta?token=2021-09-29T20%3A00%3A00Z

応答

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

注釈

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

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

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

  • デルタ クエリでは、次の表に示すように、操作とサービスの種類に応じて、一部の DriveItem プロパティは返されません。

    OneDrive for Business

    操作の種類 デルタ クエリに省略されるプロパティ
    作成/変更 ctag
    削除 ctag, name

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

    操作の種類 デルタ クエリに省略されるプロパティ
    作成/変更 該当なし
    削除 ctag, size

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

既定では、デルタ クエリの応答には、親からアクセス許可を継承し、直接共有の変更がない場合でも変更されたクエリ内のすべてのアイテムの共有情報が含まれます。 通常、これにより、共有情報が変更されたアイテムだけでなく、すべてのアイテムのアクセス許可の詳細を取得するためのフォローアップ呼び出しが行われます。 アクセス許可を変更する方法について理解するには、デルタクエリ要求に Prefer: hierarchicalsharing ヘッダーを追加します。

ヘッダーを Prefer: hierarchicalsharing 指定すると、アクセス許可階層のルートと、共有が明示的に変更されたアイテムの共有情報が返されます。 共有の変更がアイテムから共有を削除する場合、親から継承するアイテムと、一意だが共有リンクがないアイテムを区別する空の共有ファセットが見つかります。 また、この空の共有ファセットは、最初のスコープを確立するために共有されていないアクセス許可階層のルートにも表示されます。

多くのスキャンの中で、アクセス許可の変更に特に関心がある可能性があります。 デルタクエリ応答で、アクセス許可が変更された結果として、どの変更が行われたのかを明確にするために、Prefer: deltashowsharingchanges ヘッダーを指定することができます。 このヘッダーを指定すると、アクセス許可の変更が原因でデルタ クエリ応答に表示されるすべての項目に OData 注釈が @microsoft.graph.sharedChanged":"True" 付きます。 この機能は、SharePoint と OneDrive for Business には適用できますが、コンシューマーの OneDrive アカウントには適用されません。

注:

  • ヘッダーをPrefer: deltashowsharingchanges使用するには、 と Prefer: deltatraversepermissiongapsを使用Prefer: deltashowremovedasdeletedする必要があります。 これらのヘッダー値は、1 つのヘッダーに結合することができます： Prefer: deltashowremovedasdeleted, deltatraversepermissiongaps, deltashowsharingchanges。

  • アクセス許可を正しく処理するには、アプリケーションで Sites.FullControl.All アクセス許可を要求する必要があります。

スキャン シナリオの詳細については、「 ファイルを検出し、大規模な変更を検出するためのベスト プラクティス」を参照してください。

エラー応答

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

関連コンテンツ

デルタ クエリを使用して Microsoft Graph データの変更を追跡する ファイルを検出し、大規模な変更を検出するためのベスト プラクティス