listItem: delta
[アーティクル]
04/05/2024
4 人の共同作成者
フィードバック
この記事の内容
名前空間: microsoft.graph
アイテム コレクション全体の完全な読み取りを実行することなく、新しく作成、更新、または削除された リスト アイテムを取得します。
アプリでは、最初にパラメーターを指定せずに delta
を呼び出します。
このサービスでは、リストの階層の列挙、項目のページの返し、 @odata.nextLink または @odata.deltaLink のいずれかが開始されます。
@odata.deltaLink が返されるまで、アプリは @odata.nextLink で呼び出しを続ける必要があります。
すべての変更を受け取った後、それらをローカル状態に適用できます。
将来の変更をチェックするには、前の応答から @odata.deltaLink を使用してもう一度を呼び出delta
します。
差分フィードは各変更を示すのではなく、各アイテムの最新の状態を示すものです。 項目の名前が 2 回変更された場合、最新の名前で表示されるのは 1 回だけです。
さまざまな理由で、同じ項目がデルタ フィードに複数回表示される場合があります。 その場合は最後に出現したものを使用する必要があります。
このプロパティを持つ項目は、ローカル状態から削除する必要があります。
メモ: フォルダーは、すべての変更を同期した後に空の場合にのみ、ローカルで削除する必要があります。
この API は、次の国内クラウド展開 で使用できます。
グローバル サービス
米国政府機関 L4
米国政府機関 L5 (DOD)
21Vianet が運営する中国
✅
❌
❌
❌
アクセス許可
この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ 、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「 アクセス許可の種類 」を参照してください。 これらのアクセス許可の詳細については、 アクセス許可のリファレンスを参照してください 。
アクセス許可の種類
最小特権アクセス許可
特権の高いアクセス許可
委任 (職場または学校のアカウント)
Sites.Read.All
Sites.ReadWrite.All
委任 (個人用 Microsoft アカウント)
サポートされていません。
サポートされていません。
アプリケーション
Sites.Read.All
Sites.ReadWrite.All
HTTP 要求
GET /sites/{siteId}/lists/{listId}/items/delta
クエリ パラメーター
要求 URL には、次の省略可能なクエリ パラメーターを含めることができます。
パラメーター
型
説明
token
String
指定されていない場合は、階層の現在の状態を列挙します。 の場合 latest
は、最新のデルタ トークンを含む空の応答が返されます。 以前のデルタ トークンの場合は、そのトークン以降の新しい状態を返します。
このメソッドでは、応答を $select
カスタマイズするための、、 $expand
、および $top
OData クエリ パラメーター もサポートされています。
ヘッダー
値
Authorization
ベアラー {token}。 必須です。 認証と承認 の詳細については、こちらをご覧ください。
要求本文
このメソッドには、要求本文を指定しません。
応答
成功した場合、このメソッドは 200 OK
応答コードと、応答本文で listItem オブジェクトのコレクションを返します。
listItem オブジェクトのコレクションに加えて、応答には次のいずれかのプロパティも含まれます。
名前
値
説明
@odata.nextLink
URL
現在のセットにさらに変更がある場合に、次に使用可能な変更ページを取得する URL。
@odata.deltaLink
URL
現在のすべての変更が返された後に、@odata.nextLink の代わりに返される URL です。 このプロパティを使用して、今後の変更の次のセットを読み取ります。
場合によっては、サービスは、次のいずれかのエラー コードを含むエラー応答とLocation
、新しいデルタ列挙を開始する新しいnextLink
を含むヘッダーを含む応答コードを返410 Gone
します。 これは、サービスが特定のトークンの変更の一覧を提供できない場合に発生します。たとえば、クライアントが長時間切断された後に古いトークンを再利用しようとした場合や、サーバーの状態が変更され、新しいトークンが必要な場合などです。
完全な列挙が完了したら、返された項目をローカル状態と比較し、エラーの種類に基づいて指示に従います。
エラーの種類
手順
resyncChangesApplyDifferences
最後に同期したときに、サービスがローカルの変更で最新の状態であったと確信している場合は、ローカル項目をサーバーからのバージョン (削除を含む) に置き換えます。 サーバーが把握していないすべてのローカル変更をアップロードします。
resyncChangesUploadDifferences
サービスが返さなかったローカルアイテムをアップロードし、サーバーのバージョンと異なるアイテムをアップロードします。 どちらのコピーが最新のものであるかわからない場合は、両方のコピーを保持します。
再同期エラーに加え、エラーが返される方法の詳細については、「 Microsoft Graph のエラー応答とリソースの種類 」を参照してください。
例
例 1: 最初の要求
次の例は、初期要求と、この API を呼び出してローカル状態を確立する方法を示しています。
要求
次の例は、最初の要求を示しています。
GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/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.Sites["{site-id}"].Lists["{list-id}"].Items.Delta.GetAsDeltaGetResponseAsync();
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
delta, err := graphClient.Sites().BySiteId("site-id").Lists().ByListId("list-id").Items().Delta().GetAsDeltaGetResponse(context.Background(), nil)
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
var result = graphClient.sites().bySiteId("{site-id}").lists().byListId("{list-id}").items().delta().get();
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
const options = {
authProvider,
};
const client = Client.init(options);
let delta = await client.api('/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta')
.get();
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$result = $graphServiceClient->sites()->bySiteId('site-id')->lists()->byListId('list-id')->items()->delta()->get()->wait();
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
from msgraph import GraphServiceClient
graph_client = GraphServiceClient(credentials, scopes)
result = await graph_client.sites.by_site_id('site-id').lists.by_list_id('list-id').items.delta.get()
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
応答
次の例は、変更の最初のページと、現在の項目セットで使用可能な項目がそれ以上ないことを示す @odata.nextLink プロパティを含む応答を示しています。 アプリは、アイテムのすべてのページが取得されるまで、@odata.nextLink の URL の値を要求し続ける必要があります。
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"createdDateTime": "2020-06-02T22:46:58Z",
"eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC066},756\"",
"id": "1",
"lastModifiedDateTime": "2021-10-14T23:27:27Z",
"webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestFolder",
"createdBy": {
"user": {
"displayName": "John doe"
}
},
"parentReference": {
"id": "1",
"path": "Shared%20Documents",
"siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
},
"contentType": {
"id": "0x00123456789abc",
"name": "Folder"
}
},
{
"createdDateTime": "2020-06-02T22:46:58Z",
"eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC067},756\"",
"id": "2",
"lastModifiedDateTime": "2021-10-14T23:27:27Z",
"webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestItemA.txt",
"createdBy": {
"user": {
"displayName": "John doe"
}
},
"parentReference": {
"id": "2",
"path": "Shared%20Documents",
"siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
},
"contentType": {
"id": "0x00123456789abc",
"name": "Document"
}
},
{
"createdDateTime": "2020-06-02T22:46:58Z",
"eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC068},756\"",
"id": "3",
"lastModifiedDateTime": "2021-10-14T23:27:27Z",
"webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestItemB.txt",
"createdBy": {
"user": {
"displayName": "John doe"
}
},
"parentReference": {
"id": "3",
"path": "Shared%20Documents",
"siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
},
"contentType": {
"id": "0x00123456789abc",
"name": "Document"
}
}
],
"@odata.nextLink": "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}
例 2: 最後のページ要求
次の例は、セット内の最後のページを取得する要求と、この API を呼び出してローカル状態を更新する方法を示しています。
要求
次の例は、最初の要求の後の要求を示しています。
GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka
// 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.Sites["{site-id}"].Lists["{list-id}"].Items.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Token = "1230919asd190410jlka";
});
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphsites "github.com/microsoftgraph/msgraph-sdk-go/sites"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestToken := "1230919asd190410jlka"
requestParameters := &graphsites.SiteItemListItemItemsDelta()RequestBuilderGetQueryParameters{
Token: &requestToken,
}
configuration := &graphsites.SiteItemListItemItemsDelta()RequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
delta, err := graphClient.Sites().BySiteId("site-id").Lists().ByListId("list-id").Items().Delta().GetAsDeltaGetResponse(context.Background(), configuration)
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
var result = graphClient.sites().bySiteId("{site-id}").lists().byListId("{list-id}").items().delta().get(requestConfiguration -> {
requestConfiguration.queryParameters.token = "1230919asd190410jlka";
});
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
const options = {
authProvider,
};
const client = Client.init(options);
let delta = await client.api('/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka')
.get();
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Sites\Item\Lists\Item\Items\Delta\DeltaRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->token = "1230919asd190410jlka";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->sites()->bySiteId('site-id')->lists()->byListId('list-id')->items()->delta()->get($requestConfiguration)->wait();
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
from msgraph import GraphServiceClient
from msgraph.generated.sites.item.lists.item.items.delta.delta_request_builder import DeltaRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
token = "1230919asd190410jlka",
)
request_configuration = DeltaRequestBuilder.DeltaRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.sites.by_site_id('site-id').lists.by_list_id('list-id').items.delta.get(request_configuration = request_configuration)
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
応答
次の例は、という名前 TestItemB.txt
の項目が削除され、項目が最初の TestFolder
要求とこの要求の間で追加または変更され、ローカル状態を更新したことを示す応答を示しています。
アイテムの最後のページには、現在の項目セット以降の変更を取得するために後で使用できる URL を提供する @odata.deltaLink プロパティが含まれています。
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"createdDateTime": "2020-06-02T22:46:58Z",
"eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC066},756\"",
"id": "1",
"lastModifiedDateTime": "2016-03-21T20:01:37Z",
"webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestFolder",
"createdBy": {
"user": {
"displayName": "John doe"
}
},
"parentReference": {
"id": "1",
"path": "Shared%20Documents",
"siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
},
"contentType": {
"id": "0x00123456789abc",
"name": "Folder"
}
},
{
"id": "3",
"parentReference": {
"siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
},
"contentType": {
"id": "0x00123456789abc",
"name": "Document"
},
"deleted": {
"state": "deleted"
}
}
],
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}
例 3: デルタ リンク要求
一部のシナリオでは、最初にリスト内のすべての項目を既に列挙せずに、現在 deltaLink
の値を要求できます。 これは、アプリが変更についてのみ知りたいため、既存の項目について知る必要がない場合に便利です。
最新deltaLink
の を取得するには、クエリ文字列パラメーター を指定して を呼び出しますdelta
?token=latest
。
要求
次の例は要求を示しています。
GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/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.Sites["{site-id}"].Lists["{list-id}"].Items.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Token = "latest";
});
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphsites "github.com/microsoftgraph/msgraph-sdk-go/sites"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestToken := "latest"
requestParameters := &graphsites.SiteItemListItemItemsDelta()RequestBuilderGetQueryParameters{
Token: &requestToken,
}
configuration := &graphsites.SiteItemListItemItemsDelta()RequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
delta, err := graphClient.Sites().BySiteId("site-id").Lists().ByListId("list-id").Items().Delta().GetAsDeltaGetResponse(context.Background(), configuration)
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
var result = graphClient.sites().bySiteId("{site-id}").lists().byListId("{list-id}").items().delta().get(requestConfiguration -> {
requestConfiguration.queryParameters.token = "latest";
});
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
const options = {
authProvider,
};
const client = Client.init(options);
let delta = await client.api('/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=latest')
.get();
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Sites\Item\Lists\Item\Items\Delta\DeltaRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->token = "latest";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->sites()->bySiteId('site-id')->lists()->byListId('list-id')->items()->delta()->get($requestConfiguration)->wait();
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
from msgraph import GraphServiceClient
from msgraph.generated.sites.item.lists.item.items.delta.delta_request_builder import DeltaRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
token = "latest",
)
request_configuration = DeltaRequestBuilder.DeltaRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.sites.by_site_id('site-id').lists.by_list_id('list-id').items.delta.get(request_configuration = request_configuration)
プロジェクトに SDK を追加 し、authProvider インスタンスを作成 する方法の詳細については、SDK のドキュメント を参照してください。
応答
次の例は応答を示しています。
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [ ],
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}
関連コンテンツ