了解 SharePoint REST 服务Get to know the SharePoint REST service

SharePoint 包含表述性状态转移 (REST) 服务,该服务相当于现有的 SharePoint 客户端对象模型SharePoint includes a Representational State Transfer (REST) service that is comparable to the existing SharePoint client object models. 开发人员现在可以使用支持 REST Web 请求的任何技术,与 SharePoint 数据进行远程交互。Now, developers can interact remotely with SharePoint data by using any technology that supports REST web requests. 也就是说,开发人员可以使用 REST Web 技术和标准 Open Data Protocol (OData) 语法,通过 SharePoint 加载项、解决方案和客户端应用程序执行创建读取更新删除 (CRUD) 操作。This means that developers can perform Create, Read, Update, and Delete (CRUD) operations from their SharePoint Add-ins, solutions, and client applications, using REST web technologies and standard Open Data Protocol (OData) syntax.

先决条件Prerequisites

本主题假定你基本熟悉 REST 以及 REST 请求的构造方式。This topic assumes you have a basic familiarity with REST and how to construct REST requests.

SharePoint REST 服务的工作原理How the SharePoint REST service works

SharePoint 新增了使用 REST 与 SharePoint 网站进行远程交互的功能。SharePoint adds the ability for you to remotely interact with SharePoint sites by using REST. 现在可以使用支持标准 REST 功能的任何技术与 SharePoint 对象直接交互。Now you can interact directly with SharePoint objects by using any technology that supports standard REST capabilities.

若要使用 REST 访问 SharePoint 资源,可根据与所需客户端对象模型 API 对应的 OData 标准构建 REST 风格的 HTTP 请求。To access SharePoint resources using REST, construct a RESTful HTTP request by using the OData standard, which corresponds to the desired client object model API. 例如:For example:

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

SharePoint 中的 client.svc Web 服务将处理 HTTP 请求,并以 Atom 或 JavaScript 对象表示法 (JSON) 格式处理相应的响应。The client.svc web service in SharePoint handles the HTTP request, and serves the appropriate response in either Atom or JavaScript Object Notation (JSON) format. 然后,客户端应用程序必须分析相应响应。Your client application must then parse that response. 下图显示了 SharePoint REST 体系结构的高级视图。The following figure shows a high-level view of the SharePoint REST architecture.

SharePoint REST 服务体系结构SharePoint REST service architecture

SharePoint REST 服务体系结构

由于客户端对象模型易于使用且功能强大,它们保留了使用 .NET Framework、Silverlight(现已弃用)或 JavaScript (JSOM) 与 SharePoint 网站交流的主要开发选项。Because of the functionality and ease of use that client object models provide, they remain the primary development option for communicating with SharePoint sites by using the .NET Framework, Silverlight (now deprecated), or JavaScript (JSOM).

将 HTTP 命令与 SharePoint REST 服务配合使用Use HTTP commands with the SharePoint REST service

若要使用 SharePoint 内置的 REST 功能,需要使用 OData 标准构建 REST 风格的 HTTP 请求,它对应于要使用的客户端对象模型 API。To use the REST capabilities that are built into SharePoint, you construct a RESTful HTTP request by using the OData standard, which corresponds to the client object model API you want to use. client.svc Web 服务将处理 HTTP 请求,并以 Atom 或 JSON 格式处理相应的响应。The client.svc web service handles the HTTP request and serves the appropriate response in either Atom or JSON format. 然后,客户端应用程序必须分析相应响应。The client application must then parse that response.

SharePoint REST 服务终结点对应于 SharePoint 客户端对象模型中的类型和成员。The endpoints in the SharePoint REST service correspond to the types and members in the SharePoint client object models. 通过使用 HTTP 请求,你可以使用这些 REST 终结点对 SharePoint 实体(如列表和网站)执行典型的 CRUD 操作。By using HTTP requests, you can use these REST endpoints to do typical CRUD operations against SharePoint entities, such as lists and sites.

如果要对终结点执行此操作If you want to do this to an endpoint 使用此 HTTP 请求Use this HTTP request 注意事项Keep in mind
读取资源Read a resource GETGET
创建或更新资源Create or update a resource POSTPOST
  • 使用 POST 创建实体,如列表和网站。Use POST to create entities such as lists and sites.
  • SharePoint REST 服务支持将包含对象定义的 POST 命令发送到表示集合的终结点。The SharePoint REST service supports sending POST commands that include object definitions to endpoints that represent collections.
  • 对于 POST 操作,所有非必需属性都将设置为其默认值。For POST operations, any properties that aren't required are set to their default values.
  • 如果尝试将只读属性设置为 POST 操作的一部分,则该服务将返回异常。If you attempt to set a read-only property as part of a POST operation, the service returns an exception.
更新或插入资源Update or insert a resource PUTPUT
  • 使用 PUTMERGE 操作更新现有的 SharePoint 对象。Use PUT and MERGE operations to update existing SharePoint objects.
  • 任何表示对象属性 set 操作的服务终结点都同时支持 PUT 请求和 MERGE 请求。Any service endpoint that represents an object property set operation supports both PUT requests and MERGE requests.
  • 对于 MERGE 请求,设置属性是可选的;未显式设置的所有属性均保留其当前属性。For MERGE requests, setting properties is optional; any properties that you don't explicitly set keep their current property.
  • 对于 PUT 请求,如果不在对象更新中指定所有必需属性,REST 服务将返回异常。For PUT requests, if you don't specify all required properties in object updates, the REST service returns an exception.
  • 此外,未显式指定的所有可选属性都将设置为其默认属性。In addition, any optional properties you don't explicitly specify are set to their default properties.
删除资源Delete a resource DELETEDELETE
  • 对某个特定终结点 URL 使用 HTTP DELETE 命令可删除该终结点表示的 SharePoint 对象。Use the HTTP DELETE command against the specific endpoint URL to delete the SharePoint object represented by that endpoint.
  • 在可回收对象(如列表、文件和列表项)的情况中,这将导致 Recycle 操作。There are recyclable objects, such as lists, files, and list items, this results in a Recycle operation.

构建 REST URL 以访问 SharePoint 资源Construct REST URLs to access SharePoint resources

只要可能,这些 REST 端点的 URI 就会准确地模仿 SharePoint 客户端对象模型中资源的 API 签名。REST 服务的主要入口点表示网站集合以及指定上下文的网站。Whenever possible, the URI for these REST endpoints closely mimics the API signature of the resource in the SharePoint client object model. The main entry points for the REST service represent the site collection and site of the specified context.

请使用以下构造访问特定的网站集合:To access a specific site collection, use the following construction:

https://{site_url}/_api/site

请使用以下构造访问特定网站:To access a specific site, use the following construction:

https://{site_url}/_api/web

在每种情况下,server 表示服务器的名称,site 表示特定网站的名称或路径。In each case, server represents the name of the server, and site represents the name of, or path to, the specific site.

从这个起点,可以通过“遍历”对象模型并使用用斜杠 (/) 分隔的客户端对象模型中 API 的名称构造多个特定 REST URI。From this starting point, you can then construct more specific REST URIs by "walking" the object model, using the names of the APIs from the client object model separated by a forward slash (/).

此语法不适用于 SocialFeedManager 或 SocialFollowingManager REST API。This syntax doesn't apply to the SocialFeedManager or SocialFollowingManager REST APIs. 有关更多信息,请参阅:For more information, see:

有关如何根据对应客户端对象模型 API 的签名确定 SharePoint REST 终结点 URI 的更多指南,请参阅确定 SharePoint REST 服务终结点 URIFor more guidelines for determining SharePoint REST endpoint URIs from the signature of the corresponding client object model APIs, see Determine SharePoint REST service endpoint URIs.

SharePoint REST 终结点示例SharePoint REST endpoint examples

下表包含助你开始使用 SharePoint 数据的典型 REST 终结点 URL 示例。The following table contains typical REST endpoint URL examples to get you started working with SharePoint data. 向表中显示的 URL 片段追加 http://server/site/_api/,以构造完全限定的 REST URL。Prepend http://server/site/_api/ to the URL fragments shown in the table to construct a fully qualified REST URL. POST 命令必需的情况下,该表包含必须在 HTTP 请求正文中传递以创建指定的 SharePoint 项的示例数据。Where necessary for POST commands, the table contains sample data you must pass in the HTTP request body to create the specified SharePoint item. 加上引号的项表示必须用值替换的变量。Items in quotes represent variables that you must replace with your values.

说明Description URL 终结点URL endpoint HTTP 方法HTTP method 正文内容Body content
检索网站的标题Retrieves the title of a site web/title GETGET 不适用Not applicable
检索网站上的所有列表Retrieves all lists on a site lists GETGET 不适用Not applicable
检索单个列表的元数据Retrieves a single list's metadata lists/getbytitle('listname') GETGET 不适用Not applicable
检索列表中的项Retrieves items within a list lists/getbytitle('listname')/items GETGET 不适用Not applicable
检索文档的特定属性Retrieves a specific property of a document
(在本例中为文档标题)(in this case, the document title)
lists/getbytitle('listname')?select=Title GETGET 不适用Not applicable
创建列表Creates a list lists POSTPOST 参阅示例See sample
向列表添加项Adds an item to a list lists/getbytitle('listname')/items POSTPOST 参阅示例See sample

** 创建列表**示例数据:Creates a list sample data:

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

向列表添加列项示例数据:Adds an item to a list sample data:

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

在上面的 JSON 中,通过省略空格将 listname 替换为 SharePoint 列表的名称。In the above JSON, replace listname with the name of your SharePoint list by omitting the spaces.

批处理作业支持Batch job support

SharePoint Online(和本地 SharePoint 2016 或更高版本)REST 服务支持通过 OData $batch 查询选项将多个请求合并到对该服务的单个调用中。The SharePoint Online (and on-premises SharePoint 2016 or later) REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. 有关详细信息和代码示例链接,请参阅使用 REST API 发出批处理请求For details and links to code samples, see Make batch requests with the REST APIs.

OData 资源OData resources

SharePoint REST 服务主题SharePoint REST service topics

请参阅下列资源,深入了解如何使用 SharePoint REST 服务。To learn more about using the SharePoint REST service, use the following resources.

标题Title 说明Description
使用 SharePoint REST 终结点完成基本操作Complete basic operations using SharePoint REST endpoints 使用 SharePoint REST 接口执行基本的创建、读取、更新和删除 (CRUD) 操作。Perform basic create, read, update, and delete (CRUD) operations with the SharePoint REST interface.
使用 REST 处理列表和列表项Working with lists and list items with REST 使用 SharePoint REST 接口对列表和列表项执行基本的 CRUD 操作。Perform basic CRUD operations on lists and list items with the SharePoint REST interface.
使用 REST 处理文件夹和文件Working with folders and files with REST 使用 SharePoint REST 接口对文件夹和文件执行基本的 CRUD 操作。Perform basic CRUD operations on folders and files with the SharePoint REST interface.
导航 REST 服务中表示的 SharePoint 数据结构Navigate the SharePoint data structure represented in the REST service 从给定 SharePoint 项的 REST 终结点开始,导航到并访问相关项,例如该项所在的父网站或库结构。Start from a REST endpoint for a given SharePoint item, and navigate to and access-related items, such as parent sites or the library structure where that item resides.
确定 SharePoint REST 服务终结点 URIDetermine SharePoint REST service endpoint URIs 根据对应客户端对象模型 API 的签名确定 SharePoint REST 终结点 URI 的通用指南。General guidelines for determining SharePoint REST endpoint URIs from the signature of the corresponding client object model APIs.
在 SharePoint REST 请求中使用 OData 查询操作Use OData query operations in SharePoint REST requests 使用各种 OData 查询字符串操作符对你从 SharePoint REST 服务器请求的数据执行选择、筛选和排序。Use a wide range of OData query string operators to select, filter, and order the data you request from the SharePoint REST service.
使用 REST API 请求批处理Make batch requests with the REST APIs 将多个请求组合到对 REST API 服务的单个调用中。Combine multiple requests into a single call to the REST service.
使用 REST 服务同步 SharePoint 项Synchronize SharePoint items using the REST service 使用 SharePoint REST 服务中的 GetListItemChangesSinceToken 资源同步 SharePoint 和加载项或服务之间的项。Synchronize items between SharePoint and your add-ins or services by using the GetListItemChangesSinceToken resource, part of the SharePoint REST service.
使用 REST API 和 jQuery 上传文件Upload a file by using the REST API and jQuery 本文中的代码示例使用 REST 接口和 jQuery AJAX 请求,将本地文件添加到文档库,然后更改表示已上传文件的列表项的属性。The code examples in this article use the REST interface and jQuery AJAX requests to add a local file to the Documents library, and then change properties of the list item that represents the uploaded file.
使用 REST 接口设置列表的自定义权限Set custom permissions on a list by using the REST interface SharePoint 网站、列表和列表项是 SecurableObject 的类型,继承了其父级权限。SharePoint sites, lists, and list items are types of SecurableObject, which inherits the permissions of its parent. 若要设置对象的自定义权限,需要中断其继承,使其停止从父级继承权限,然后通过添加或删除角色分配定义新的权限。To set custom permissions for an object, you need to break its inheritance so that it stops inheriting permissions from its parent, and then define new permissions by adding or removing role assignments.
SharePoint 工作流基础知识SharePoint workflow fundamentals 通过 SharePoint Server 2013 中的 Search REST 服务以及任何支持 REST Web 请求的技术,向客户端和移动应用程序添加搜索功能。Add search functionality to client and mobile applications using the Search REST service in SharePoint Server 2013 and any technology that supports REST web requests.
SharePoint 的社交源 REST API 引用Social feed REST API reference for SharePoint 源相关任务的 SharePoint REST 终结点。SharePoint REST endpoints for feed-related tasks.
关注好友及 SharePoint 的内容 REST API 引用Following people and content REST API reference for SharePoint 下列人员和内容的 SharePoint REST 终结点。SharePoint REST endpoints for following people and content.
开发 SharePoint 加载项Develop SharePoint Add-ins 查找更详细的文章和资源来帮助你构建 SharePoint 加载项的高级功能。Find in-depth articles and resources to help you build advanced capabilities into your SharePoint Add-ins.