使用 SharePoint REST 终结点完成基本操作

可使用 SharePoint 表述性状态转移 (REST) 接口，执行基本的创建、读取、更新和删除 (CRUD) 操作。 REST 接口公开其他 SharePoint 客户端 API 中的所有 SharePoint 实体和操作。 REST 的优势之一是，无需添加对任何 SharePoint 库或客户端程序集的引用。 而是向相应的终结点发出 HTTP 请求，以检索或更新网站、列表和列表项等 SharePoint 实体。

有关 SharePoint REST 接口及其体系结构的介绍，请参阅了解 SharePoint REST 服务。

若要了解如何使用核心 SharePoint 实体，请参阅使用 REST 处理列表和列表项和使用 REST 处理文件夹和文件。

有关展示了如何在用 C# 编写的 ASP.NET Web 应用程序上下文中执行多个此类操作的示例，请参阅 SharePoint-Add-in-REST-OData-BasicDataOperations。

若要了解 SharePoint 平台上的 API 集，请参阅在 SharePoint 中选择合适的 API 集。

若要了解如何使用其他客户端 API，请参阅：

• 使用 SharePoint 中的 JavaScript 库代码完成基本操作- 使用 SharePoint 客户端库代码完成基本操作
• 生成访问 SharePoint 的 Windows Phone 应用

SharePoint REST 服务中的 HTTP 操作

SharePoint REST 服务终结点对应于 SharePoint 客户端对象模型中的类型和成员。 借助 HTTP 请求，可以使用这些 REST 终结点对 SharePoint 实体（如列表和网站）执行典型的 CRUD（创建、读取、更新和删除）操作。

通常，表示 Read 操作的端点映射到 HTTP GET 命令。表示创建操作的端点映射到 HTTP POST 命令，而表示更新或插入操作的端点则映射到 HTTP PUT 命令。

在 SharePoint 中，使用 POST 可以创建注入列表和网站的工件。 SharePoint REST 服务支持将包括对象定义的 POST 命令发送到表示集合的终结点。 例如，您可以将 ATOM 中包括新列表定义的 POST 命令发送到以下 URL，以创建 SharePoint 列表：

http://<site url>/_api/web/lists

对于 POST 操作，任何不需要的属性将设置为其默认值。 如果您尝试在 POST 操作过程中设置只读属性，则服务将返回异常。

使用 PUT、PATCH 和 MERGE 操作可以更新现有 SharePoint 对象。 任何表示对象属性 set 操作的服务终结点均支持 PUT 请求和 MERGE 请求。 对于 MERGE 请求，设置属性是可选的；任何未显式设置的属性将保留其当前属性。 但是，对于 PUT 命令，任何未显式设置的属性将设置为其默认属性。 此外，如果您在使用 HTTP PUT 命令时未在对象更新中指定所有必需的属性，则 REST 服务将返回异常。

对某个特定终结点 URL 使用 HTTP DELETE 命令可删除该终结点表示的 SharePoint 对象。 对于可循环的对象（如列表、文件和列表项），这将导致 Recycle 操作。

使用 SharePoint REST 接口读取数据

若要使用 SharePoint 内置的 REST 功能，请您使用 OData 标准（它对应于您要使用的客户端对象模型 API）构建 REST 样式的 HTTP 请求。 每个 SharePoint 实体都在您的目标 SharePoint 网站上的终结点上公开，其元数据由 XML 或 JSON 格式表示。 您可以用任何一种语言（包括但不限于 JavaScript 和 C#）发出 HTTP 请求。

若要读取 REST 终结点中的信息，必须知道终结点 URL，以及在相应终结点处公开的 SharePoint 实体的 OData 表示形式。 例如，若要检索特定 SharePoint 网站中的所有列表，请向 http://<site url>/_api/web/lists 发出 GET 请求。 可以在浏览器中转到此 URL，并查看返回的 XML。 在代码中发出请求时，可以指定是以 XML 格式，还是以 JSON 格式接收列表的 OData 表示形式。

下面的 C# 代码展示了如何发出此 GET 请求，以使用 JQuery 返回网站中所有列表的 JSON 表示形式。 还有一个前提是，拥有在 accessToken 变量中存储的有效 OAuth 访问令牌。 如果在加载项 Web 内执行此调用，无需使用访问令牌，就像在 SharePoint 托管加载项中执行调用一样。 请注意，不能从浏览器客户端上运行的代码中获取访问令牌。 必须通过在服务器上运行的代码获取访问令牌。

若要详细了解如何获取访问令牌，请参阅 SharePoint 加载项的上下文令牌 OAuth 流和 SharePoint 加载项的授权代码 OAuth 流。

HttpWebRequest endpointRequest =
  (HttpWebRequest)HttpWebRequest.Create(
  "http://<site url>/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization",
  "Bearer " + accessToken);
HttpWebResponse endpointResponse =
  (HttpWebResponse)endpointRequest.GetResponse();

若要在 JavaScript 中编写加载项，同时使用 SharePoint 跨域库，那么此请求就会略有不同。 在这种情况下，无需提供访问令牌。

下面的代码展示了此请求，即要使用跨域库，且希望以 XML 格式（而不是 JSON 格式）接收列表的 OData 表示形式。 （由于 Atom 是默认响应格式，因此无需添加 Accept 头。）若要详细了解如何使用跨域库，请参阅使用跨域库通过加载项访问 SharePoint 数据。

var executor = new SP.RequestExecutor(appweburl);
executor.executeAsync(
  {
    url: appweburl +
          "/_api/SP.AppContextSite(@target)/web/lists?@target='" +
          hostweburl + "'",
    method: "GET",
    success: successHandler,
    error: errorHandler
  }
);

下面的示例代码展示了如何使用 C# 请求获取网站中所有列表的 JSON 表示形式。 前提是，拥有要在 accessToken 变量中存储的 OAuth 访问令牌。

HttpWebRequest endpointRequest = (HttpWebRequest)HttpWebRequest.Create(sharepointUrl.ToString() + "/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization", "Bearer " + accessToken);
HttpWebResponse endpointResponse = (HttpWebResponse)endpointRequest.GetResponse();

获取未与资源一起返回的属性

当您检索资源时将返回多个属性值，但对于某些属性，您必须直接向属性终结点发送 GET 请求。 这是显示 SharePoint 实体的属性的典型行为。

以下示例显示了如何通过将属性名称附加到资源端点来获取属性。 示例从 File 资源获取 Author 属性的值。

http://<site url>/_api/web/getfilebyserverrelativeurl('/<folder name>/<file name>')/author

若要获取 JSON 格式结果，请添加设置为 "application/json;odata=verbose" 的 Accept 头。

使用 REST 接口写入数据

您可以通过构建发送到适当终结点的 REST 样式的 HTTP 请求来创建和更新 SharePoint 实体，就像您阅读数据一样。 但是，一个关键的区别是您使用 POST 请求。 当您更新实体时，您还通过将一个 PUT 或 MERGE HTTP 请求方法作为 X-HTTP-Method 键的值添加到您的请求标头，来传递该 HTTP 请求方法。 MERGE 方法仅更新您指定的实体的属性，而 PUT 方法会将现有实体替换为您在 POST 的正文中提供的一个新实体。 使用 DELETE 方法可删除实体。 当您创建或更新实体时，您必须在 HTTP 请求的正文中提供您要创建或更改的实体的 OData 表示。

创建、更新和删除 SharePoint 实体时的另一个重要考虑是，如果您不是使用 OAuth 对请求进行授权，则这些操作需要将服务器的请求窗体摘要值作为 X-RequestDigest 标头的值。 您可以通过以下方式检索此值：向 发送具有空正文的 http://<site url>/_api/contextinfo 请求，在 d:FormDigestValue 终结点返回的 XML 中提取 节点的值。 以下示例演示了向 C# 中的 contextinfo 终结点发出的 HTTP 请求。

HttpWebRequest endpointRequest =(HttpWebRequest)HttpWebRequest.Create(
                                    "http://<site url>/_api/contextinfo");
endpointRequest.Method = "POST";
endpointRequest.Accept = "application/json;odata=verbose";
HttpWebResponse endpointResponse = (HttpWebResponse)endpointRequest.GetResponse();

若要使用 SharePoint 加载项授权和身份验证中介绍的身份验证和授权流，无需在请求中添加请求摘要。

若要使用 JavaScript 跨域库，SP.RequestExecutor 会负责处理获取和发送表单摘要值。

若要创建 SharePoint 托管 SharePoint 加载项，无需单独发出 HTTP 请求来检索表单摘要值。 相反，可以从 SharePoint 页面（如果页面使用默认母版页的话）JavaScript 代码中检索值，如下面的示例所示，其中使用 JQuery 并创建列表。

jQuery.ajax({
        url: "http://<site url>/_api/web/lists",
        type: "POST",
        data:  JSON.stringify({ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true,
 'BaseTemplate': 100, 'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test' }
),
        headers: {
            "accept": "application/json;odata=verbose",
            "content-type": "application/json;odata=verbose",
            "content-length": <length of post body>,
            "X-RequestDigest": $("#__REQUESTDIGEST").val()
        },
        success: doSuccess,
        error: doError
});

以下示例演示如何更新在前面的示例中创建的列表。 该示例更改列表的标题、使用 JQuery，并假定您在 SharePoint 托管的外接程序中执行此操作。

jQuery.ajax({
        url: "http://<site url>/_api/web/lists/GetByTitle('Test')",
        type: "POST",
        data: JSON.stringify({ '__metadata': { 'type': 'SP.List' }, 'Title': 'New title' }),
        headers: {
            "X-HTTP-Method":"MERGE",
            "accept": "application/json;odata=verbose",
            "content-type": "application/json;odata=verbose",
            "content-length": <length of post body>,
            "X-RequestDigest": $("#__REQUESTDIGEST").val(),
            "IF-MATCH": "*"
        },
        success: doSuccess,
        error: doError
});

请求头中 IF-MATCH 键的值就是，指定列表或列表项的 etag 值的位置。 此值仅适用于列表和列表项，有助于避免在更新这些实体时出现并发问题。 上一示例对此值使用星号 (*)，只要无需担心并发问题，即可使用这样的值。 否则，应执行检索实体的 GET 请求，以获取 etag 值或列表/列表项。 所生成 HTTP 响应的响应头会以 ETag 键值的形式传递 etag。 实体元数据中也包含此值。

下面的示例展示了包含列表信息的 XML 节点的开始 <entry> 标记。 m:etag 属性包含 etag 值。

<entry xml:base="http://site url/_api/" xmlns=http://www.w3.org/2005/Atom
       xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
       xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
       xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml" m:etag=""1"">

使用 REST 创建网站

下面的示例展示了如何使用 JavaScript 创建网站。

jQuery.ajax({
    url: "http://<site url>/_api/web/webinfos/add",
    type: "POST",
    data: JSON.stringify(
        {'parameters': {
            '__metadata':  {'type': 'SP.WebInfoCreationInformation' },
            'Url': 'RestSubWeb',
            'Title': 'RestSubWeb',
            'Description': 'REST created web',
            'Language':1033,
            'WebTemplate':'sts',
            'UseUniquePermissions':false}
        }
    ),
    headers: {
        "accept": "application/json; odata=verbose",
        "content-type":"application/json;odata=verbose",
        "content-length": <length of post body>,
        "X-RequestDigest": $("#__REQUESTDIGEST").val()
    },
    success: doSuccess,
    error: doError
});

注意

将 WebTemplate 设置为“sts”可创建新式主页。 若要创建经典主页，请将 WebTemplate 设置为“sts#0”。

REST 请求如何因环境而异

构建和发送 HTTP 请求可能会因语言、库和外接程序类型而不同，因此在将请求从一个环境转换到另一个环境时，经常需要更改一个或多个请求组件。 例如，jQuery AJAX 请求使用 data 和 type 参数指定请求正文和类型，但跨域库请求使用 body 和 method 参数指定这些值。

以下各节介绍各环境之间的其他常见差异。

获取和发送表单摘要值的方式因加载项而异

发送 POST 请求时，请求必须在 X-RequestDigest 标头中加入窗体摘要值。 但是，您获取和发送值的方式因外接程序而异：

• 在 SharePoint 托管加载项中，可以直接传递下面的头：

  "X-RequestDigest": $("#__REQUESTDIGEST").val()

• 在使用 OAuth 的云托管的外接程序，首先通过向 contextinfo 终结点发送请求来检索窗体摘要值，然后将其添加到请求，如 使用 REST 界面写入数据中所述。

• 在使用 JavaScript 跨域库的云托管加载项中，无需指定表单摘要值。 默认情况下为 SP。RequestExecutor 会自动为你处理此问题。 (它还处理内容长度值。)

使用 OAuth 的加载项必须在请求中传递访问令牌

云托管加载项使用 OAuth 或跨域库，授予对 SharePoint 数据的访问权限。 代码在远程 Web 服务器上运行的加载项组件必须使用 OAuth 授予对 SharePoint 数据的访问权限。 在这种情况下，需要添加 Authorization 头，才能发送访问令牌。 有关将授权标头添加到 HTTPWebRequest 对象的示例，请参阅使用 SharePoint REST 接口读取数据。

注意

用 JavaScript 编写的云托管加载项组件必须使用跨域库中的 SP.RequestExecutor 对象，才能访问 SharePoint 数据。 无需在跨域库请求中添加访问令牌。

若要详细了解 OAuth 访问令牌及其获取方式，请参阅 SharePoint 加载项的上下文令牌 OAuth 流和 SharePoint 加载项的授权代码 OAuth 流。

跨域请求中的终结点 URI 使用 SP.AppContextSite 更改上下文

将请求发送到请求的 url 属性中指定的资源终结点。 终结点 URI 使用以下格式：

<site url>/_api/<context>/<resource> (示例， https://contoso.com/_api/web/lists)

跨域库请求在访问外接程序 Web 上的数据时使用此格式，这是跨域库请求的默认上下文。 但是，如果要访问主机 Web 或其他网站集中的数据，该请求需要初始化主机 Web 或其他网站集作为上下文。 为此，它们在 URI 中使用 SP.AppContextSite 终结点，如表 1 中所示。 表 1 中的示例 URI 使用 @target 别名在查询字符串中发送目标 URL，因为此 URL 包含一个特殊字符 (':')。

注意

云托管加载项必须有加载项 Web 实例，才能在使用跨域库时访问 SharePoint 数据。

表 1. 使用 SP.AppContextSite 终结点更改请求的上下文

外接程序类型	跨域数据访问方案	示例终结点 URI
云托管	JavaScript 加载项组件使用跨域库访问主机 Web 数据	<app web url>/_api/SP.AppContextSite(@target)/web/lists?@target='<host web url>'
云托管	JavaScript 加载项组件使用跨域库访问网站集（而不是主机 Web）中的数据（仅租户范围内的加载项）	<app web url>/_api/SP.AppContextSite(@target)/web/title?@target='<target site url>'
SharePoint 托管	加载项 Web 组件访问其他网站集中的数据（仅租户范围内的加载项）	<app web url>/_api/SP.AppContextSite(@target)/web/title?@target='<target site url>'

注意

跨域库数据访问方案还需要相应的外接程序权限。 有关详细信息，请参阅访问主机 Web 数据和访问各网站集的数据。

SharePoint 加载项可以从加载项页面的查询字符串中，获取加载项 Web URL 和主机 Web URL，如下面的代码示例所示。 该示例还演示如何引用跨域库，它在主机 Web 上的 SP.RequestExecutor.js 文件中定义。 此示例假定加载项是通过 SharePoint 启动。 若要了解如何在加载项不是通过 SharePoint 启动时正确设置 SharePoint 上下文，请参阅 SharePoint 加载项的授权代码 OAuth 流。

var hostweburl;
var appweburl;

// Get the URLs for the add-in web the host web URL from the query string.
$(document).ready(function () {
  //Get the URI decoded URLs.
  hostweburl = decodeURIComponent(getQueryStringParameter("SPHostUrl"));
  appweburl = decodeURIComponent(getQueryStringParameter("SPAppWebUrl"));

  // Load the SP.RequestExecutor.js file.
  $.getScript(hostweburl + "/_layouts/15/SP.RequestExecutor.js", runCrossDomainRequest);
});

// Build and send the HTTP request.
function runCrossDomainRequest() {
  var executor = new SP.RequestExecutor(appweburl);
  executor.executeAsync({
      url: appweburl + "/_api/SP.AppContextSite(@target)/web/lists?@target='" + hostweburl + "'",
      method: "GET",
      headers: { "Accept": "application/json; odata=verbose" },
      success: successHandler,
      error: errorHandler
  });
}

// Get a query string value.
// For production add-ins, you may want to use a library to handle the query string.
function getQueryStringParameter(paramToRetrieve) {
  var params = document.URL.split("?")[1].split("&");
  var strParams = "";
  for (var i = 0; i < params.length; i = i + 1) {
    var singleParam = params[i].split("=");
    if (singleParam[0] == paramToRetrieve) return singleParam[1];
  }
}
??? // success and error callback functions

REST 请求中使用的属性

表 2 列出了 SharePoint REST 服务 HTTP 请求中的常用属性。

表 2. 在 HTTP 请求中使用 REST 请求属性的情况

属性	何时需要使用	说明
url	所有请求	REST 资源端点的 URL。 例如：http://<site url>/_api/web/lists
method（或 type）	所有请求	HTTP 请求方法： GET （针对读取操作）和 POST（针对写入操作）。 POST 请求可以通过指定 DELETE 标头中的 MERGE、 PUT 或 X-HTTP-Method 动词执行更新或删除操作。
body（或 data）	在请求正文中发送数据的 POST 请求	POST 请求的正文。 发送无法在端点 URI 中发送的数据（例如复杂类型）。 用于 content-length 标头。
Authentication 头	要使用 OAuth 验证用户的远程加载项。使用 JavaScript 或跨域库时不适用	发送 OAuth 访问令牌（从 Microsoft 访问控制服务 (ACS) 安全令牌服务器获得），该令牌用于针对请求验证用户。 示例： "Authorization": "Bearer " + accessToken，其中 accessToken 表示存储令牌的变量。 令牌必须通过服务器端代码检索。
X-RequestDigest 标头	POST 请求（SP.RequestExecutor 请求除外）	使用 OAuth 的远程加载项可以从终结点获取表单摘要值 http://<site url>/_api/contextinfo 。 SharePoint 托管的外接程序可从 #__REQUESTDIGEST 页面控件获取在 SharePoint 页面上的可用值。 请参阅 通过使用 REST 界面写入数据。
accept 标头	返回 SharePoint 元数据的请求	为来自服务器的响应数据指定格式。 默认格式为 application/atom+xml。 例如："accept":"application/json;odata=verbose"
content-type 标头	在请求正文中发送数据的 POST 请求	为客户端发送到服务器的数据指定格式。 默认格式为 application/atom+xml。 例如："content-type":"application/json;odata=verbose"
content-length 标头	在请求正文中发送数据的 POST 请求（SP.RequestExecutor 请求除外）	指定内容的长度。 例如："content-length":requestBody.length
IF-MATCH 头	DELETE、MERGE 或 PUT 操作的 POST 请求，主要用于更改列表和库。	提供一种用于验证正在更改的对象自上次检索后尚未更改的方法。 或者，可以指定覆盖任何更改，如以下示例所示： "IF-MATCH":"*"
X-HTTP-Method 标头	POST、 DELETE 或 MERGE 操作的 PUT 请求	用于指定请求执行了一项更新或删除操作。 例如："X-HTTP-Method":"PUT"
binaryStringRequestBody	在正文中发送二进制数据的 SP.RequestExecutor POST 请求	指定请求正文是否为二进制字符串。 Boolean。
binaryStringResponseBody	返回二进制数据的 SP.RequestExecutor 请求	指定响应是否为二进制字符串。 Boolean。

批处理作业支持

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

另请参阅

• 了解 SharePoint REST 服务
• SharePoint 加载项的安全数据访问和客户端对象模型
• 在 SharePoint 中处理外部数据
• OData 资源
• 使用 REST 接口对列表设置自定义权限
• 开发 SharePoint 加载项