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服務的屬性。