使用 Microsoft Graph 中的 SharePoint 网站Working with SharePoint sites in Microsoft Graph

Microsoft Graph 中的 SharePoint API 支持以下核心情形:The SharePoint API in Microsoft Graph supports the following core scenarios:

  • 访问 SharePoint 网站列表驱动器(文档库)Access to SharePoint sites, lists, and drives (document libraries)
  • 支持对 site 资源进行只读访问(无法创建新网站)Read-only support for site resources (no ability to create new sites)
  • 支持对 listslistItemsdriveItems 进行读写访问Read-write support for lists, listItems, and driveItems
  • 用 SharePoint ID、URL 或相对路径表示的 Address 资源Address resources by SharePoint ID, URL, or relative path

SharePoint API 公开了三种主要资源类型:The SharePoint API exposes three major resource types:

下面的示例展示了 listItem 资源。The following is an example of a listItem resource.

{
  "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",
}

资源通过三种不同的方式公开数据:Resources expose data in three different ways:

  • 属性(如 idname)公开简单值。Properties (like id and name) expose simple values.
  • Facet(如 fieldscreatedBy)公开复杂值。Facets (like fields and createdBy) expose complex values.
  • 引用(如 items)指向其他资源的集合。References (like items) point to collections of other resources.

可以使用 expand 查询参数展开 URL 中的引用;例如 ?expand=fieldsYou can expand references in your URL with the expand query parameter; for example, ?expand=fields. 可以使用 select 查询参数请求特定属性和 facet;例如 ?select=id,nameYou can request specific properties and facets with the select query parameter; for example, ?select=id,name. 默认情况下,虽然大部分属性和 Facet 都会返回,但所有引用都会被隐藏。By default, most properties and facets are returned while all references are hidden. 为了提高效率,建议将 selectexpand 指定为仅返回你关注的数据。For efficiency, we recommend that you specify select and expand to only return the data you care about.

SharePoint API 根资源SharePoint API root resources

以下示例与 https://graph.microsoft.com/v1.0 有关。The following examples are relative to https://graph.microsoft.com/v1.0.

路径Path 说明Description
/sites/root/sites/root 组织的默认网站Organization's default site.
/sites/{site-id}/sites/{site-id} 通过其 ID 访问特定网站Access a specific site by its ID.
/sites/{site-id}/drive/sites/{site-id}/drive 访问给定网站的默认驱动器(文档库)。Access the default drive (document library) for the given site.
/sites/{site-id}/drives/sites/{site-id}/drives 枚举网站下的驱动器(文档库)。Enumerate the drives (document libraries) under the site.
/sites/{site-id}/sites/sites/{site-id}/sites 枚举网站下的子网站。Enumerate the sub-sites under the site.
/sites/{site-id}/lists/sites/{site-id}/lists 枚举网站下的列表Enumerate the lists under the site.
/sites/{site-id}/lists/{list-id}/items/sites/{site-id}/lists/{list-id}/items 枚举列表下的 listItemEnumerate the listItems under the list.
/groups/{group-id}/sites/root/groups/{group-id}/sites/root 访问组的团队网站Access a group's team site.

还可以使用 SharePoint 主机名,后面加上冒号和网站的相对路径,来为网站寻址。可以选择将另一个冒号置于末尾,转回为资源模型寻址。Sites can also be addressed by path by using the SharePoint hostname, followed by a colon and the relative path to the site. You can optionally transition back to addressing the resource model by putting another colon at the end.

PathPath 说明Description
/sites/contoso.sharepoint.com:/teams/hr/sites/contoso.sharepoint.com:/teams/hr https://contoso.sharepoint.com/teams/hr 相关联的网站The site associated with https://contoso.sharepoint.com/teams/hr
/sites/contoso.sharepoint.com:/teams/hr:/drive/sites/contoso.sharepoint.com:/teams/hr:/drive 访问此网站的默认驱动器Access the default drive for this site.

现有 SharePoint 开发人员须知Note for existing SharePoint developers

Microsoft Graph SharePoint API 与 CSOM API 有几个主要区别。The Microsoft Graph SharePoint API has a few key differences with the CSOM APIs. 网站 资源映射到 SPWebThe site resource maps to SPWeb. 网站集中的根网站 (SPWeb) 具有 siteCollection facet,其中包含有关 SPSite 的信息。The root site (SPWeb) in a site collection has a siteCollection facet, which contains information about the SPSite. 由于网站 ID 只在其网站集中是唯一的,因此按 ID 为网站寻址需要提供网站集标识符和网站标识符。Because IDs for sites are only unique within their site collection, addressing a site by ID requires providing both the site collection identifier and the site identifier.

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

仅使用主机名构造的 URL 将指向默认网站集中的根网站 (SPWeb)。A URL constructed with only the hostname will point to the root site (SPWeb) in the default site collection.

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

仅使用主机名和 siteCollection (SPSite) ID 构造的 URL 将指向给定网站集中的根网站 (SPWeb)。A URL constructed with only the hostname and siteCollection (SPSite) ID will point to the root site (SPWeb) in the given site collection.

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