站点: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$topOData 查询参数 来自定义响应。

请求标头

标头
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

响应

以下示例显示了包含第一页更改的响应,以及指示当前网站集中没有更多网站可用的 @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

响应

以下示例显示了一个响应,该响应指示在初始请求和此请求之间删除了名为 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": {}
        }
    ]
}

在某些情况下,你可能想要请求当前 deltaLink 值,而不首先枚举所有网站、列表和 Web。 如果你的应用只想要了解更改,而不需要了解现有网站,则它可能很有用。 若要检索最新的 deltaLink,请使用查询字符串参数 ?token=latest调用 delta

注意: 如果要维护资源的完整本地表示形式,则必须对初始枚举使用 delta 。 使用 delta 是确保读取所需全部数据的唯一方法。

请求

以下示例显示了一个请求。

GET https://graph.microsoft.com/v1.0/sites/delta?token=latest

响应

以下示例显示了相应的响应。

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [ ],
  "@odata.deltaLink": "https://graph.microsoft.com/v1.0/sites/delta?token=1230919asd190410jlka"
}

另请参阅