次の方法で共有

driveItem: delta

  • [アーティクル]

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

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}。 必須です。 認証と認可についての詳細をご覧ください。
deltaExcludeParent 文字列。 この要求ヘッダーが含まれている場合、応答には、階層内の親項目ではなく、変更された項目が含まれます。

要求本文

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

応答

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

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

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

例

例 1: 最初の要求

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

要求

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

GET https://graph.microsoft.com/beta/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/beta/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 を提供します。

サービスが特定のトークンの変更の一覧を提供できない場合があります (たとえば、クライアントが長い間切断された後に古いトークンを再利用しようとした場合や、サーバーの状態が変更され、新しいトークンが必要な場合など)。 このような場合、サービスはエラー コードを含むエラー応答と、新しいデルタ列挙を最初から開始する新しい nextLink を含むLocation ヘッダーを含む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 プロパティには、 path の値は含まれません。 これは、フォルダーの名前を変更しても、フォルダーの子孫が デルタから返されないために発生します。 デルタを使用する場合は、常に 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: deltashowremovedasdeletedとPrefer: deltatraversepermissiongapsを使用する必要があります。 これらのヘッダー値は、1 つのヘッダーに結合することができます： Prefer: deltashowremovedasdeleted, deltatraversepermissiongaps, deltashowsharingchanges。

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

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

エラー応答

詳細な再同期エラーに加えて、エラーが返される方法の詳細については、「 エラー応答 」を参照してください。

関連コンテンツ

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