名前空間: microsoft.graph
重要
Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
アイテム コレクション全体を完全に読み取ることなく、新しく作成、更新、または削除された リスト アイテム を取得します。
アプリでは、最初にパラメーターを指定せずに delta を呼び出します。
サービスはリストの階層の列挙を開始し、アイテムのページと、 @odata.nextLink または @odata.deltaLink のいずれかを返します。
アプリは、@odata.deltaLink が返されるまで、@odata.nextLink で呼び出し続ける必要があります。
すべての変更を受け取ったら、それらをローカル州に適用できます。
将来の変更をチェックするには、前の応答の @odata.deltaLink を使用して delta を再度呼び出します。
差分フィードは各変更を示すのではなく、各アイテムの最新の状態を示すものです。 項目の名前が 2 回変更された場合、最新の名前で 1 回だけ表示されます。
さまざまな理由により、同じ項目が差分フィードに複数回表示される場合があります。 その場合は最後に出現したものを使用する必要があります。
削除されたアイテムは、 削除された ファセットとともに返されます。
Deleted アイテムが削除され、復元できないことを示します。
このプロパティを持つアイテムは、ローカル州から削除する必要があります。
メモ: すべての変更を同期した後にフォルダーが空の場合にのみ、ローカルで削除する必要があります。
この 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 |
文字列 |
指定しない場合は、階層の現在の状態を列挙します。
latest の場合、最新のデルタ トークンを含む空の応答を返します。 以前のデルタ トークンの場合は、そのトークン以降の新しい状態を返します。 |
このメソッドでは、応答をカスタマイズするための $select、 $expand、および $topOData クエリ パラメーター もサポートされています。
| ヘッダー |
値 |
| Authorization |
ベアラー {token}。 必須です。
認証と認可についての詳細をご覧ください。 |
要求本文
このメソッドには、要求本文を指定しません。
応答
成功した場合、このメソッドは 200 OK 応答コードと、応答本文で listItem オブジェクトのコレクションを返します。
応答には、 listItem オブジェクトのコレクションに加えて、次のいずれかのプロパティも含まれます。
| 名前 |
値 |
説明 |
| @odata.nextLink |
URL |
現在のセットにさらに変更がある場合に、次に使用可能な変更ページを取得するための URL。 |
| @odata.deltaLink |
URL |
現在のすべての変更が返された後に、@odata.nextLink の代わりに返される URL です。 このプロパティを使用して、今後の変更セットを読み取ります。 |
場合によっては、サービスによって、次のいずれかのエラー コードを含むエラー応答と、新しいデルタ列挙を開始する新しいnextLinkを含む Location ヘッダーを含む410 Gone応答コードが返されます。 これは、サービスが特定のトークンに対する変更の一覧を提供できない場合に発生します。たとえば、クライアントが長時間切断された後に古いトークンを再利用しようとする場合や、サーバーの状態が変化して新しいトークンが必要な場合などです。
完全な列挙が完了したら、返された項目をローカル州と比較し、エラーの種類に基づく指示に従います。
| エラーの種類 |
手順 |
resyncChangesApplyDifferences |
前回同期したときのローカルの変更によりサービスが最新であったことが確実な場合は、ローカル項目をサーバーのバージョン (削除を含む) に置き換えます。 サーバーが把握していないすべてのローカル変更をアップロードします。 |
resyncChangesUploadDifferences |
サービスが返さなかったローカル アイテムをアップロードし、サーバーのバージョンとは異なるアイテムをアップロードします。 どちらのコピーが最新であるかわからない場合は、両方のコピーを保存してください。 |
再同期エラーに加えて、エラーが返される方法の詳細については、「 Microsoft Graph のエラー応答とリソースの種類」を参照してください。
例
例 1: 最初の要求
次の例は、最初の要求と、この API を呼び出してローカル状態を確立する方法を示しています。
要求
次の例は、最初の要求を示しています。
GET https://graph.microsoft.com/beta/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();
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-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.Sites().BySiteId("site-id").Lists().ByListId("list-id").Items().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.sites().bySiteId("{site-id}").lists().byListId("{list-id}").items().delta().get();
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')
.version('beta')
.get();
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$result = $graphServiceClient->sites()->bySiteId('site-id')->lists()->byListId('list-id')->items()->delta()->get()->wait();
Import-Module Microsoft.Graph.Beta.Sites
Get-MgBetaSiteListItemDelta -SiteId $siteId -ListId $listId
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta 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.sites.by_site_id('site-id').lists.by_list_id('list-id').items.delta.get()
応答
次の例は、変更の最初のページと、現在のアイテム セットでこれ以上使用できないことを示す @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/beta/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/beta/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";
});
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphsites "github.com/microsoftgraph/msgraph-beta-sdk-go/sites"
//other-imports
)
requestToken := "1230919asd190410jlka"
requestParameters := &graphsites.ItemListsItemItemsDeltaRequestBuilderGetQueryParameters{
Token: &requestToken,
}
configuration := &graphsites.ItemListsItemItemsDeltaRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Sites().BySiteId("site-id").Lists().ByListId("list-id").Items().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.sites().bySiteId("{site-id}").lists().byListId("{list-id}").items().delta().get(requestConfiguration -> {
requestConfiguration.queryParameters.token = "1230919asd190410jlka";
});
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')
.version('beta')
.get();
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\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();
Import-Module Microsoft.Graph.Beta.Sites
Get-MgBetaSiteListItemDelta -SiteId $siteId -ListId $listId -Token "1230919asd190410jlka"
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.sites.item.lists.item.items.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 = "1230919asd190410jlka",
)
request_configuration = RequestConfiguration(
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)
応答
次の例は、 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/beta/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を取得するには、クエリ文字列パラメーター ?token=latest を指定して delta を呼び出します。
要求
次の例は要求を示しています。
GET https://graph.microsoft.com/beta/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";
});
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphsites "github.com/microsoftgraph/msgraph-beta-sdk-go/sites"
//other-imports
)
requestToken := "latest"
requestParameters := &graphsites.ItemListsItemItemsDeltaRequestBuilderGetQueryParameters{
Token: &requestToken,
}
configuration := &graphsites.ItemListsItemItemsDeltaRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Sites().BySiteId("site-id").Lists().ByListId("list-id").Items().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.sites().bySiteId("{site-id}").lists().byListId("{list-id}").items().delta().get(requestConfiguration -> {
requestConfiguration.queryParameters.token = "latest";
});
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')
.version('beta')
.get();
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\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();
Import-Module Microsoft.Graph.Beta.Sites
Get-MgBetaSiteListItemDelta -SiteId $siteId -ListId $listId -Token "latest"
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.sites.item.lists.item.items.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.sites.by_site_id('site-id').lists.by_list_id('list-id').items.delta.get(request_configuration = request_configuration)
応答
次の例は応答を示しています。
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [ ],
"@odata.deltaLink": "https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}
関連コンテンツ