了解 SharePoint REST 服务

SharePoint 包含表述性状态转移 (REST) 服务，该服务相当于现有的 SharePoint 客户端对象模型。 开发人员现在可以使用支持 REST Web 请求的任何技术，与 SharePoint 数据进行远程交互。 也就是说，开发人员可以使用 REST Web 技术和标准 Open Data Protocol (OData) 语法，通过 SharePoint 加载项、解决方案和客户端应用程序执行创建、读取、更新和删除 (CRUD) 操作。

先决条件

本主题假定你基本熟悉 REST 以及 REST 请求的构造方式。

SharePoint REST 服务的工作原理

SharePoint 新增了使用 REST 与 SharePoint 网站进行远程交互的功能。 现在，您可以使用任何支持标准 REST 功能的技术直接与 SharePoint 对象进行交互。

若要使用 REST 访问 SharePoint 资源，可根据与所需客户端对象模型 API 对应的 OData 标准构建 REST 风格的 HTTP 请求。 例如：

CSOM

var items = List.GetByTitle(listname).GetItems();

http

GET https://{site_url}/_api/lists/getbytitle('{list_name}')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

SharePoint 中的 client.svc Web 服务将处理 HTTP 请求，并以 Atom 或 JavaScript 对象表示法 (JSON) 格式处理相应的响应。 然后，客户端应用程序必须分析相应响应。 下图显示了 SharePoint REST 体系结构的高级视图。

SharePoint REST 服务体系结构

由于客户端对象模型易于使用且功能强大，它们保留了使用 .NET Framework、Silverlight（现已弃用）或 JavaScript (JSOM) 与 SharePoint 网站交流的主要开发选项。

将 HTTP 命令与 SharePoint REST 服务配合使用

若要使用 SharePoint 内置的 REST 功能，需要使用 OData 标准构建 REST 风格的 HTTP 请求，它对应于要使用的客户端对象模型 API。 client.svc Web 服务将处理 HTTP 请求，并以 Atom 或 JSON 格式处理相应的响应。 然后，客户端应用程序必须分析相应响应。

SharePoint REST 服务终结点对应于 SharePoint 客户端对象模型中的类型和成员。 通过使用 HTTP 请求，你可以使用这些 REST 终结点对 SharePoint 实体（如列表和网站）执行典型的 CRUD 操作。

如果要对终结点执行此操作	使用此 HTTP 请求	注意事项
读取资源	GET
创建或更新资源	POST	使用 POST 创建实体，如列表和网站。 SharePoint REST 服务支持将包含对象定义的 POST 命令发送到表示集合的终结点。 对于 POST 操作，所有非必需属性都将设置为其默认值。 如果尝试将只读属性设置为 POST 操作的一部分，则该服务将返回异常。
更新或插入资源	PUT	使用 PUT 和 MERGE 操作更新现有的 SharePoint 对象。 任何表示对象属性 set 操作的服务终结点都同时支持 PUT 请求和 MERGE 请求。 对于 MERGE 请求，设置属性是可选的；未显式设置的所有属性均保留其当前属性。 对于 PUT 请求，如果不在对象更新中指定所有必需属性，REST 服务将返回异常。 此外，未显式指定的所有可选属性都将设置为其默认属性。
删除资源	DELETE	对某个特定终结点 URL 使用 HTTP DELETE 命令可删除该终结点表示的 SharePoint 对象。 在可回收对象（如列表、文件和列表项）的情况中，这将导致 Recycle 操作。

构建 REST URL 以访问 SharePoint 资源

只要可能，这些 REST 端点的 URI 就会准确地模仿 SharePoint 客户端对象模型中资源的 API 签名。 REST 服务的主要入口点表示网站集合以及指定上下文的网站。

请使用以下构造访问特定的网站集合：

https://{site_url}/_api/site

请使用以下构造访问特定网站：

https://{site_url}/_api/web

在每种情况下，server 表示服务器的名称，site 表示特定网站的名称或路径。

从这个起点，可以通过“遍历”对象模型并使用用斜杠 (/) 分隔的客户端对象模型中 API 的名称构造多个特定 REST URI。

此语法不适用于 SocialFeedManager 或 SocialFollowingManager REST API。 有关更多信息，请参阅：

• SharePoint 的社交源 REST API 引用
• 关注好友及 SharePoint 的内容 REST API 引用

有关如何根据对应客户端对象模型 API 的签名确定 SharePoint REST 终结点 URI 的更多指南，请参阅确定 SharePoint REST 服务终结点 URI。

SharePoint REST 终结点示例

下表包含助你开始使用 SharePoint 数据的典型 REST 终结点 URL 示例。 向表中显示的 URL 片段追加 http://server/site/_api/，以构造完全限定的 REST URL。 在 POST 命令必需的情况下，该表包含必须在 HTTP 请求正文中传递以创建指定的 SharePoint 项的示例数据。 加上引号的项表示必须用值替换的变量。

说明	URL 终结点	HTTP 方法	正文内容
检索网站的标题	web/title	GET	不适用
检索网站上的所有列表	lists	GET	不适用
检索单个列表的元数据	lists/getbytitle('listname')	GET	不适用
检索列表中的项	lists/getbytitle('listname')/items	GET	不适用
检索列表的特定属性 （本例中为列表标题）	lists/getbytitle('listname')?select=Title	GET	不适用
创建列表	lists	POST	参阅示例
向列表添加项	lists/getbytitle('listname')/items	POST	参阅示例

创建列表示例数据：

{
  "__metadata": {
    "type": "SP.List"
  },
  "AllowContentTypes": true,
  "BaseTemplate": 104 ,
  "ContentTypesEnabled": true,
  "Description": "My list description ",
  "Title": "RestTest "
}

向列表添加列项示例数据：

{
  "__metadata": {
    "type": "SP.Data.listname.ListItem"
  },
  "Title": "MyItem"
}

在上面的 JSON 中，通过省略空格将 listname 替换为 SharePoint 列表的名称。

批处理作业支持

SharePoint Online（和本地 SharePoint 2016 或更高版本）REST 服务支持通过 OData $batch 查询选项将多个请求合并到对该服务的单个调用中。 有关详细信息和代码示例链接，请参阅使用 REST API 发出批处理请求。

OData 资源

• 使用 WCF 开发面向服务的应用程序
• Open Data Protocol
• OData 协议 URI 约定
• 寻址服务操作
• OData 协议操作
• 错误条件

SharePoint REST 服务主题

请参阅下列资源，深入了解如何使用 SharePoint REST 服务。

标题	说明
使用 SharePoint REST 终结点完成基本操作	使用 SharePoint REST 接口执行基本的创建、读取、更新和删除 (CRUD) 操作。
使用 REST 处理列表和列表项	使用 SharePoint REST 接口对列表和列表项执行基本的 CRUD 操作。
使用 REST 处理文件夹和文件	使用 SharePoint REST 接口对文件夹和文件执行基本的 CRUD 操作。
导航 REST 服务中表示的 SharePoint 数据结构	从给定 SharePoint 项的 REST 终结点开始，导航到并访问相关项，例如该项所在的父网站或库结构。
确定 SharePoint REST 服务终结点 URI	根据对应客户端对象模型 API 的签名确定 SharePoint REST 终结点 URI 的通用指南。
在 SharePoint REST 请求中使用 OData 查询操作	使用各种 OData 查询字符串操作符对你从 SharePoint REST 服务器请求的数据执行选择、筛选和排序。
使用 REST API 请求批处理	将多个请求组合到对 REST API 服务的单个调用中。
使用 REST 服务同步 SharePoint 项	使用 SharePoint REST 服务中的 GetListItemChangesSinceToken 资源同步 SharePoint 和加载项或服务之间的项。
使用 REST API 和 jQuery 上传文件	本文中的代码示例使用 REST 接口和 jQuery AJAX 请求，将本地文件添加到文档库，然后更改表示已上传文件的列表项的属性。
使用 REST 接口设置列表的自定义权限	SharePoint 网站、列表和列表项是 SecurableObject 的类型，继承了其父级权限。 若要设置对象的自定义权限，需要中断其继承，使其停止从父级继承权限，然后通过添加或删除角色分配定义新的权限。
SharePoint 工作流基础知识	通过 SharePoint Server 2013 中的 Search REST 服务以及任何支持 REST Web 请求的技术，向客户端和移动应用程序添加搜索功能。
SharePoint 的社交源 REST API 引用	源相关任务的 SharePoint REST 终结点。
关注好友及 SharePoint 的内容 REST API 引用	下列人员和内容的 SharePoint REST 终结点。
开发 SharePoint 加载项	查找更详细的文章和资源来帮助你构建 SharePoint 加载项的高级功能。