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.