使用 Microsoft Graph 中的 SharePoint 网站

项目
01/07/2024

Microsoft Graph 中的 SharePoint API 支持以下核心情形：

访问 SharePoint 网站、列表和驱动器（文档库）
支持对 site 资源进行只读访问（无法创建新网站）
支持对 lists、listItems 和 driveItems 进行读写访问
租户级 SharePointSettings 的读写支持
用 SharePoint ID、URL 或相对路径表示的 Address 资源

SharePoint API 公开了三种主要资源类型：

网站 (顶级对象)
List
ListItem

下面的示例展示了 listItem 资源。

{
  "fields": {
    "Title": "Access card",
    "Employee": "Ryan Gregg",
    "EmployeeId": "10",
    "CardSerial": "01235492",
    "Alias": "RGregg",
    "ID": 1,
    "ContentType": "Item",
    "Modified": "2016-09-19T23:15:25-07:00",
    "Created": "2016-09-19T23:15:25-07:00"
  },
  "createdBy": {
    "user": {
      "id": "b757fdcb-0271-4807-b243-504139e4ba04",
      "displayName": "Ryan Gregg"
    }
  },
  "createdDateTime": "2016-09-20T06:15:25Z",
  "eTag": "48e941c3-9515-4c48-9760-c07c90c79d48,1",
  "id": "4",
  "lastModifiedBy": {
    "user": {
      "id": "b757fdcb-0271-4807-b243-504139e4ba04",
      "displayName": "Ryan Gregg"
    }
  },
  "lastModifiedDateTime": "2016-09-20T06:15:25Z",
}

资源通过三种不同的方式公开数据：

属性（如 id 和 name）公开简单值。
Facet（如 fields 和 createdBy）公开复杂值。
引用（如 items）指向其他资源的集合。

可以使用 expand 查询参数展开 URL 中的引用；例如 ?expand=fields。可以使用 select 查询参数请求特定属性和 facet；例如 ?select=id,name。默认情况下，虽然大部分属性和 Facet 都会返回，但所有引用都会被隐藏。为了提高效率，建议将 select 和 expand 指定为仅返回你关注的数据。

SharePoint API 根资源

以下示例与 https://graph.microsoft.com/v1.0 有关。

路径	说明
/sites/root	组织的默认网站。
/sites/{site-id}	通过其 ID 访问特定网站。
/sites/{site-id}/drive	访问给定网站的默认驱动器（文档库）。
/sites/{site-id}/drives	枚举网站下的驱动器（文档库）。
/sites/{site-id}/sites	枚举网站下的子网站。
/sites/{site-id}/lists	枚举网站下的列表。
/sites/{site-id}/lists/{list-id}/items	枚举列表下的 listItem。
/groups/{group-id}/sites/root	访问组的团队网站。
/admin/sharepoint/settings	访问组织的管理员级别设置。

还可以使用 SharePoint 主机名（后跟冒号和网站的相对路径）按路径对网站进行寻址。可以选择通过将另一个冒号放在末尾来转换回资源模型寻址。

Path	说明
/sites/contoso.sharepoint.com:/teams/hr	与 https://contoso.sharepoint.com/teams/hr 相关联的网站
/sites/contoso.sharepoint.com:/teams/hr:/drive	访问此网站的默认驱动器。

现有 SharePoint 开发人员须知

Microsoft Graph SharePoint API 与 CSOM API 有几个主要区别。网站资源映射到 SPWeb。网站集中的根网站 (SPWeb) 具有 siteCollection facet，其中包含有关 SPSite 的信息。由于网站 ID 只在其网站集中是唯一的，因此按 ID 为网站寻址需要提供网站集标识符和网站标识符。

GET https://graph.microsoft.com/v1.0/sites/{hostname},{spsite-id},{spweb-id}/

仅使用主机名构造的 URL 指向根网站， SPWeb (默认网站集中的) 。

GET https://graph.microsoft.com/v1.0/sites/{hostname}

仅使用主机名和 siteCollection 构造的 URL (SPSite) ID 指向给定网站集中的根网站 (SPWeb) 。

GET https://graph.microsoft.com/v1.0/sites/{hostname},{spsite-id}

仅使用 siteCollection () SPSite ID 构造的 URL 指向给定网站集中的根网站 (SPWeb) 。

GET https://graph.microsoft.com/v1.0/sites/{spsite-id}

从 SharePoint REST v1 API URL 映射到 Microsoft 图形 API URL

以下示例可帮助熟悉 SharePoint REST v1 API URL 模式的开发人员将其用例适应类似的 Microsoft 图形 API URL 模式。

模式 1

访问与指定 SPWeb URL 关联的网站。

GET https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-server-relative-url}

示例 1

以下示例返回有关与 URL https://contoso.sharepoint.com/teams/hr/benefits关联的SPWeb站点的信息。请注意， benefits 是网站集内的 (SPWebSPSite) 。https://contoso.sharepoint.com/teams/hr

GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/teams/hr/benefits

模式 2

访问与以下组件关联的列表项。

组件	说明
{hostname}	站点的主机名。
{site-server-relative-url}	站点的相对于服务器的 URL (`SPWeb`) 。
{list-id}	站点中) (`SPList` 列表的 GUID ID。
{item-id}	列表项的 GUID 或整数 ID (`SPListItem` 列表中) 。

以下示例演示包含上述组件的请求。

GET https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-server-relative-url}:/lists/{list-id}/items/{item-id}

示例 2

以下示例返回有关 SPListItem 具有整数 ID 的信息，该整数 ID 42 属于具有 GUID ID 5771e865-4e91-48b8-a0de-35a25d4e52fe的列表。此列表属于与 URL https://contoso.sharepoint.com/teams/hr/benefits关联的SPWeb网站。

GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/teams/hr/benefits:/lists/5771e865-4e91-48b8-a0de-35a25d4e52fe/items/42