使用 Microsoft Graph 中的 SharePoint 网站

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

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

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

下面的示例展示了 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",
}

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

  • 属性(如 idname)公开简单值。
  • Facet(如 fieldscreatedBy)公开复杂值。
  • 引用(如 items)指向其他资源的集合。

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

SharePoint API 根资源

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

路径 说明
/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/beta/sites/{hostname},{spsite-id},{spweb-id}/

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

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

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

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

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

GET https://graph.microsoft.com/beta/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/beta/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/beta/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/beta/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/beta/sites/contoso.sharepoint.com:/teams/hr/benefits:/lists/5771e865-4e91-48b8-a0de-35a25d4e52fe/items/42