了解 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 请求。 例如:
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 |
|
更新或插入资源 | PUT |
|
删除资源 | DELETE |
|
构建 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。 有关更多信息,请参阅:
有关如何根据对应客户端对象模型 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 资源
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 加载项的高级功能。 |