SharePoint REST API

博客地址：http://blog.csdn.net/FoxDave

上一节讲了SharePoint REST API的一些基本操作，本节将继续介绍一些关于SharePoint REST API的内容。

构建和发送HTTP请求常常会根据不同的语言、库和Add-in而产生变化，所以你需要在切换环境的时候对请求做相应的修改。例如，JQuery AJAX请求使用data和type参数来指定请求的主体和类型，但是跨域库请求使用body和method参数来指定这些值。

下面在讲一些公共的跨环境差异。

SharePoint Add-in获取和发送表单摘要认证的方式

当你发送一个POST请求时，请求必须在X-RequestDigest头中包含表单摘要认证。但是在SharePoint Add-in中则不是。

对于SharePoint承载的add-in，可以直接传递下面的头：

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

对于云承载的Add-in分两种情况：使用OAuth的，首先通过发送请求到contextinfo终结点来获取表单摘要认证的值，然后将它添加到请求中；使用JavaScript跨域库的，你不需要指定表单摘要认证的值。默认情况下，SP.RequestExecutor方法会为你自动处理它，也会处理content-length的值。

使用OAuth的SharePoint Add-ins必须在请求中传递访问令牌

云承载的Add-in使用OAuth或跨域库来授权访问SharePoint的数据。远程Web服务器执行的代码必须使用OAuth来授权访问SharePoint的数据。在这种情况下，你需要包含Authorization头来发送访问令牌。

注意用JavaScript写的云承载的Add-in组件必须使用跨域库中的SP.RequestExecutor对象来访问SharePoint数据。跨域库请求不需要包含访问令牌。

在跨域请求中使用SP.AppContextSite终结点来更改context

发送到资源终结点的请求在请求的url中被指定，使用如下格式：

_<site url>_/_api/ _<context>_/ _<resource>_ (example, https://contoso.com/_api/web/lists)

跨域库请求在访问Add-in的网站的数据时使用此种格式，是默认的上下文。但是如果要访问承载该Add-in的网站或者是其他的网站，请求需要初始化一个上下文对象。使用URI中的SP.AppContextSite端点，如下表：

Add-in type	Cross-domain data access scenario	Example endpoint URI
Cloud-hosted	JavaScript add-in component accessing host web data by using the cross-domain library	/_api/SP.AppContextSite(@target)/web/lists?@target=' '
Cloud-hosted	JavaScript add-in component accessing data in a site collection other than the host web by using the cross-domain library (tenant-scoped add-ins only)	/_api/SP.AppContextSite(@target)/web/title?@target=' '
SharePoint-hosted	Add-in web component accessing data in another site collection (tenant-scoped add-ins only)	/_api/SP.AppContextSite(@target)/web/title?@target=' '

SharePoint Add-ins可以从查询字符串中获取Add-in网站的URL和承载网站的URL，下面的代码展示了如何获取。同时下面的代码也展示了如何引用在SP.RequestExecutor.js文件中定义的跨域库。

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请求中使用的属性

下表展示了通常在HTTP请求中使用的SharePoint REST服务的属性。

Properties	When required	Description
url	All requests	The URL of the REST resource endpoint. Example: http://<site url>/_api/web/lists
method (or type)	All requests	The HTTP request method: GET for read operations and POST for write operations. POST requests can perform update or delete operations by specifying a DELETE, MERGE, or PUT verb in the X-HTTP-Method header.
body (or data)	POST requests that send data in the request body	The body of the POST request. Sends data (such as complex types) that can't be sent in the endpoint URI. Used with the content-length header.
Authentication header	Remote add-ins that are using OAuth to authenticate users. Does not apply when using JavaScript or the cross domain library.	Sends the OAuth access token (obtained from a Microsoft Access Control Service (ACS) secure token server) that's used to authenticate the user for the request. Example: "Authorization": "Bearer " + accessToken, where accessToken represents the variable that stores the token. Tokens must be retrieved by using server-side code.
X-RequestDigest header	POST requests (except SP.RequestExecutor requests)	Remote add-ins that use OAuth can get the form digest value from the http://<site url>/_api/contextinfo endpoint. SharePoint-hosted add-ins can get the value from the #__REQUESTDIGEST page control if it's available on the SharePoint page. See Writing data by using the REST interface.
accept header	Requests that return SharePoint metadata	Specifies the format for response data from the server. The default format is application/atom+xml. Example: "accept":"application/json;odata=verbose"
content-type header	POST requests that send data in the request body	Specifies the format of the data that the client is sending to the server. The default format is application/atom+xml. Example: "content-type":"application/json;odata=verbose"
content-length header	POST requests that send data in the request body (except SP.RequestExecutor requests)	Specifies the length of the content. Example: "content-length":requestBody.length
IF-MATCH header	POST requests for DELETE, MERGE, or PUT operations, primarily for changing lists and libraries.	Provides a way to verify that the object being changed has not been changed since it was last retrieved. Or, lets you specify to overwrite any changes, as shown in the following example: "IF-MATCH":"*"
X-HTTP-Method header	POST requests for DELETE, MERGE, or PUT operations	Used to specify that the request performs an update or delete operation. Example: "X-HTTP-Method":"PUT"
binaryStringRequestBody	SP.RequestExecutor POST requests that send binary data in the body	Specifies whether the request body is a binary string. Boolean.
binaryStringResponseBody	SP.RequestExecutor requests that return binary data	Specifies whether the response is a binary string. Boolean.