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.