站点:delta
本文内容
获取新创建、更新或删除 的网站 ,而无需执行整个网站集的完整读取。
站点 的增量 函数调用类似于 GET 请求,只是通过在一个或多个调用中适当应用状态令牌 ,可以查询站点 中的增量更改。 它允许你维护和同步用户 站点 的本地存储,而无需每次从服务器提取所有 站点 。
应用程序在不指定任何参数的情况下调用 API。
该服务开始枚举网站,并返回对这些网站的更改页,并附带 @odata.nextLink 或 @odata.deltaLink 。
应用程序应继续使用 @odata.nextLink 进行调用,直到响应中有 @odata.deltaLink 。
收到所有更改后,可以将它们应用到本地状态。
若要监视将来的更改,请在上一响应中使用 @odata.deltaLink 调用增量 API。
标记为已删除的任何资源都应从本地状态中删除。
此 API 可用于以下国家级云部署 。
全局服务
美国政府 L4
美国政府 L5 (DOD)
由世纪互联运营的中国
✅
❌
❌
❌
权限
为此 API 选择标记为最低特权的权限。 只有在应用需要它时 ,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型 。 要了解有关这些权限的详细信息,请参阅 权限参考 。
权限类型
最低特权权限
更高特权权限
委派(工作或学校帐户)
Sites.Read.All
Sites.ReadWrite.All
委派(个人 Microsoft 帐户)
不支持。
不支持。
应用程序
Sites.Read.All
Sites.ReadWrite.All
HTTP 请求
GET /sites/delta
查询参数
在请求 URL 中,可以包含以下可选查询参数。
参数
类型
说明
令牌
String
如果值为 latest
,则调用返回具有最新增量令牌的空响应。 如果值是以前的增量标记,则调用将返回自颁发该令牌以来的新状态。
此方法还支持 $select
、 $expand
和 $top
OData 查询参数 来自定义响应。
标头
值
Authorization
持有者 {token}。 必填。
请求正文
请勿提供此方法的请求正文。
响应
如果成功,此方法将在响应正文中返回 200 OK
响应代码和 site 对象集合。
除了 网站 对象的集合外,响应还包含以下属性之一。
名称
值
说明
@odata.nextLink
URL
一个 URL,用于检索下一个可用更改页(如果当前集中存在更多更改)。
@odata.deltaLink
URL
返回所有当前更改后返回的 URL,而不是 @odata.nextLink 。 使用此属性可读取将来的下一组更改。
在某些情况下,服务返回一个 410 Gone
响应代码,其中包含一个错误响应,该响应包含以下错误代码之一,以及一个 Location
标头,该标头包含一个新的 nextLink
,用于启动新的增量枚举。 当服务无法为给定令牌提供更改列表时,会发生此情况;例如,如果客户端在长时间断开连接后尝试重用旧令牌,或者服务器状态已更改,并且需要新令牌。
完成完整枚举后,将返回的站点与本地状态进行比较,并根据错误类型按照说明进行操作。
错误类型
说明
resyncChangesApplyDifferences
将任何本地站点替换为服务器 (包括删除) (如果确定服务在上次同步时本地更改是最新的)。 上载服务器并不清楚的任意本地更改。
resyncChangesUploadDifferences
上传服务未返回的任何本地站点,并上传与服务器版本不同的任何站点。 如果不确定哪个副本是最新的,请保留这两个副本。
有关详细信息,请参阅 Microsoft Graph 错误响应和资源类型 。
示例
示例 1:初始请求
以下示例演示初始请求以及如何调用此 API 来建立本地状态。
请求
以下示例显示了初始请求。
GET https://graph.microsoft.com/v1.0/sites/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.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().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().delta().get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
let delta = await client.api('/sites/delta')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$result = $graphServiceClient->sites()->delta()->get()->wait();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
from msgraph import GraphServiceClient
graph_client = GraphServiceClient(credentials, scopes)
result = await graph_client.sites.delta.get()
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应
以下示例显示了包含第一页更改的响应,以及指示当前网站集中没有更多网站可用的 @odata.nextLink 属性。 你的应用应继续请求 @odata.nextLink 的 URL 值,直到检索到网站的所有页面。
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"id": "contoso.sharepoint.com,da60e844-ba1d-49bc-b4d4-d5e36bae9019,712a596e-90a1-49e3-9b48-bfa80bee8740",
"name": "teamSiteA"
},
{
"id": "contoso.sharepoint.com,da60e844-ba1d-49bc-b4d4-d5e36bae9019,0271110f-634f-4300-a841-3a8a2e851851",
"name": "teamSiteB"
},
{
"id": "contoso.sharepoint.com,da60e844-ba1d-49bc-b4d4-d5e36bae9019,0271110f-634f-4300-a841-3a8a2e851851",
"name": "teamSiteC"
}
],
"@odata.nextLink": "https://graph.microsoft.com/v1.0/sites/delta?token=1230919asd190410jlka"
}
示例 2:最后一页请求
以下示例显示了访问集中最后一页的请求,以及如何调用此 API 来更新本地状态。
请求
以下示例显示了初始请求之后的请求。
GET https://graph.microsoft.com/v1.0/sites/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.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.SitesDelta()RequestBuilderGetQueryParameters{
Token: &requestToken,
}
configuration := &graphsites.SitesDelta()RequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
delta, err := graphClient.Sites().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().delta().get(requestConfiguration -> {
requestConfiguration.queryParameters.token = "1230919asd190410jlka";
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
let delta = await client.api('/sites/delta?token=1230919asd190410jlka')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Sites\Delta\DeltaRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->token = "1230919asd190410jlka";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->sites()->delta()->get($requestConfiguration)->wait();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
from msgraph import GraphServiceClient
from msgraph.generated.sites.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.delta.get(request_configuration = request_configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应
以下示例显示了一个响应,该响应指示在初始请求和此请求之间删除了名为 All Company
的网站,以更新本地状态。
网站的最后一页包括 @odata.deltaLink 属性,该属性提供 URL,以后可用于检索自当前网站集以来的更改。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites",
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/sites/delta?$deltatoken=b2vm2fSuZ-V_1Gdq4ublGPD4lReifRNHYMGxkFf0yz2fTqr9U6jMyWv8hihThODJCO_5I7JbpAFLQAIOUzYXhCPl0jlQdjTC1o24iBe81xQyAWJOiP3q1xyMKjlfZUawWok3Njc_LIrrSgrdSydhsVCL6XYpRkYGJ9JDYxFMiJw2vUs1QC_S0cW6hqYQnOimeA918dQZwD8pJI9oUJryV2Ow-7Dj9p18p1I6pFg044k.xipVdgMKlOFIlXzPipsKzlFJbYUTD1sGiFiPe7uZA7Q",
"value": [
{
"createdDateTime": "2024-03-11T02:36:04Z",
"name": "All Company",
"displayName": "All Company",
"isPersonalSite": false,
"id": "bd565af7-7963-4658-9a77-26e11ac73186",
"root": {}
}
]
}
示例 3:增量链接请求
在某些情况下,你可能想要请求当前 deltaLink
值,而不首先枚举所有网站、列表和 Web。 如果你的应用只想要了解更改,而不需要了解现有网站,则它可能很有用。
若要检索最新的 deltaLink
,请使用查询字符串参数 ?token=latest
调用 delta
。
注意: 如果要维护资源的完整本地表示形式,则必须对初始枚举使用 delta
。 使用 delta
是确保读取所需全部数据的唯一方法。
请求
以下示例显示了一个请求。
GET https://graph.microsoft.com/v1.0/sites/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.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.SitesDelta()RequestBuilderGetQueryParameters{
Token: &requestToken,
}
configuration := &graphsites.SitesDelta()RequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
delta, err := graphClient.Sites().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().delta().get(requestConfiguration -> {
requestConfiguration.queryParameters.token = "latest";
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
let delta = await client.api('/sites/delta?token=latest')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Sites\Delta\DeltaRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->token = "latest";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->sites()->delta()->get($requestConfiguration)->wait();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
from msgraph import GraphServiceClient
from msgraph.generated.sites.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.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/delta?token=1230919asd190410jlka"
}
另请参阅