driveItem: delta

[アーティクル]
10/02/2023

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

要求本文

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

応答

成功した場合、このメソッドは応答本文で 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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Delta.GetAsDeltaGetResponseAsync();



mgc drives items delta get --drive-id {drive-id} --drive-item-id {driveItem-id}



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Delta().GetAsDeltaGetResponse(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").delta().get();


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/drive/root/delta')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->delta()->get()->wait();


Import-Module Microsoft.Graph.Files

Get-MgDriveItemDelta -DriveId $driveId -DriveItemId $driveItemId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').delta.get()

応答

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

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].DeltaWithToken("{token}").GetAsDeltaWithTokenGetResponseAsync();



mgc drives items delta-with-token get --token {token-id} --drive-id {drive-id} --drive-item-id {driveItem-id}



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
token := "{token}"
delta, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").DeltaWithToken(&token).GetAsDeltaWithTokenGetResponse(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").deltaWithToken("{token}").get();


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/drive/root/delta(token='MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM3OTQzNzQwODQ3NTcwMDAwOzU4NTk2OTY0NDslMjM7JTIzOyUyMzA')')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->deltaWithToken('{token}', )->get()->wait();

Snippet not available


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').delta_with_token("{token}").get()

応答

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

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 を提供します。

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

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

例 3: 現在の deltaLink の取得

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

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

要求

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Token = "latest";
});



mgc drives items delta get --drive-id {drive-id} --drive-item-id {driveItem-id}



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)


requestToken := "latest"

requestParameters := &graphdrives.DriveItemItemItemDeltaWithRequestBuilderGetQueryParameters{
	Token: &requestToken,
}
configuration := &graphdrives.DriveItemItemItemDeltaWithRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Delta().GetAsDeltaGetResponse(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.token = "latest";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/drive/root/delta?token=latest')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Delta\DeltaRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->token = "latest";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->delta()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Files

Get-MgDriveItemDelta -DriveId $driveId -DriveItemId $driveItemId -Token "latest"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.delta.delta_request_builder import DeltaRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		token = "latest",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').delta.get(request_configuration = request_configuration)

応答

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 でのみサポートされています。

要求

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Token = "2021-09-29T20:00:00Z";
});



mgc drives items delta get --drive-id {drive-id} --drive-item-id {driveItem-id}



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)


requestToken := "2021-09-29T20:00:00Z"

requestParameters := &graphdrives.DriveItemItemItemDeltaWithRequestBuilderGetQueryParameters{
	Token: &requestToken,
}
configuration := &graphdrives.DriveItemItemItemDeltaWithRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Delta().GetAsDeltaGetResponse(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.token = "2021-09-29T20:00:00Z";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/drive/root/delta?token=2021-09-29T20:00:00Z')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Delta\DeltaRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->token = "2021-09-29T20:00:00Z";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->delta()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Files

Get-MgDriveItemDelta -DriveId $driveId -DriveItemId $driveItemId -Token "2021-09-29T20:00:00Z"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.delta.delta_request_builder import DeltaRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		token = "2021-09-29T20:00:00Z",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').delta.get(request_configuration = request_configuration)

応答

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

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

操作の種類	デルタクエリに省略されるプロパティ
作成/変更	該当なし
削除	`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 データの変更を追跡するファイルを検出し、大規模な変更を検出するためのベストプラクティス

次の方法で共有

driveItem: delta

アクセス許可

HTTP 要求

関数パラメーター

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

要求ヘッダー

要求本文

応答

例

例 1: 最初の要求

要求

応答

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

要求

応答

例 3: 現在の deltaLink の取得

要求

応答

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

要求

応答

注釈

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

エラー応答

フィードバック

その他のリソース

次の方法で共有

driveItem: delta

アクセス許可

HTTP 要求

関数パラメーター

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

要求ヘッダー

要求本文

応答

例

例 1: 最初の要求

要求

応答

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

要求

応答

例 3: 現在の deltaLink の取得

要求

応答

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

要求

応答

注釈

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

エラー応答

関連コンテンツ

フィードバック

その他のリソース

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