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端点，如下表：

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

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