SharePoint REST API - 基本操作（一）

部落格地址：http://blog.csdn.net/FoxDave

本文講述如何應用SharePoint的REST介面完成基本的增刪查改操作。

使用SharePoint客戶端API和REST服務進行開發

你可以使用SharePoint提供的REST介面執行基本的增刪查改操作。REST介面暴露了所有的SharePoint客戶端API中可操作的物件和操作。使用REST的優勢是你可以不新增SharePoint類庫或客戶端的引用，而是使用HTTP請求訪問特定的終結點來獲取或更新SharePoint物件，如網站，列表和列表項。可以檢視之前的文章瞭解SharePoint REST介面和架構的概述。

在之後的文章中也會對每個操作進行細緻的介紹。

在SharePoint REST服務中的HTTP操作

SharePoint REST服務的終結點與客戶端物件模型是對應的關係。通過使用HTTP請求，你可以使用REST終結點來對SharePoint物件執行經典的增刪查改操作，如列表和網站。

通常情況下，終結點的讀取操作對應HTTP的GET方法，更新對應POST，更新或新增操作對應PUT。在SharePoint中，使用POST來建立如列表或網站的SharePoint物件，方式是通過SharePoint REST服務傳送包含物件定義的POST命令到集合終結點來建立物件，比如傳送請求到http://<site url>/_api/web/lists來建立一個列表。

對於POST操作，任何不必填的屬性都會被設定為它們的預設值。如果你想要通過POST操作設定只讀屬性，服務會返回異常。

使用PUT和MERGE操作來更新已經存在的SharePoint物件。任何一個表示設定屬性的服務終結點都支援PUT和MERGE兩種請求。對於MERGE請求，設定屬性是可選的，任何沒在請求中顯式宣告的屬性都將保留當前的屬性值。但是對於PUT操作，相當於重新整理，任何沒在請求中顯式宣告的屬性都將被設定為預設值。而且，如果你不指定所有必填的屬性，服務會返回異常。

使用HTTP的DELETE操作請求指定的終結點來刪除SharePoint物件，對於能夠回收的物件如列表、檔案和列表項，執行的是刪除到回收站的操作。

通過SharePoint REST介面來讀取資料

使用SharePoint內建的REST，你可以構建一個使用OData標準的REST的HTTP請求，跟你想要使用的客戶端物件模型是對應的。每個SharePoint物件都暴露在一個SharePoint網站的終結點，它們的資料是XML或者JSON格式。你可以使用任何語言構建HTTP請求，不只限於JavaScript和C#。

從REST終結點讀取資訊，你必須瞭解終結點的URL和暴露在其上的SharePoint物件的OData描述。例如，獲取SharePoint網站的所有列表資訊，你可以使用GET操作的請求到http://<site url>/_api/web/lists。你可以在瀏覽器中訪問這個URL來檢視返回的XML。當你在程式碼中執行請求的時候，你可以指定獲取JSON還是XML格式的資料。

下面的程式碼展示瞭如何通過JQuery使用GET請求來返回一個網站的所有列表資料JSON資料。這裡假設你有一個可用的OAuth訪問令牌儲存在accessToken變數中。當你在網站內部進行呼叫是不需要這個令牌的。注意你是不能通過執行在客戶端的瀏覽器來獲取訪問令牌的，而是必須在伺服器上獲取。關於如何獲取訪問令牌，我們將在之後的文章中進行介紹。

HttpWebRequest endpointRequest =
  (HttpWebRequest)HttpWebRequest.Create(
  "http://<site url>/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization", 
  "Bearer " + accessToken);
HttpWebResponse endpointResponse =
  (HttpWebResponse)endpointRequest.GetResponse();

如果使用SharePoint跨域庫的話，程式碼會有一些不同。在這種情況下你不需要提供訪問令牌。下面的程式碼展示了在使用跨域庫時請求的樣子，取而代之的會獲取XML型別的返回資料。關於跨域庫的使用以後有機會也會給大家進行分享。

var executor = new SP.RequestExecutor(appweburl);
executor.executeAsync(
    {
        url:
            appweburl +
            "/_api/SP.AppContextSite(@target)/web/lists?@target='" +
            hostweburl + "'",
        method: "GET",
        success: successHandler,
        error: errorHandler
    }
);

下面的程式碼展示瞭如何用C#獲取相關資料的示例，同樣假定你已經獲取到了訪問令牌。

HttpWebRequest endpointRequest = (HttpWebRequest)HttpWebRequest.Create(sharepointUrl.ToString() + "/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization", "Bearer " + accessToken);
HttpWebResponse endpointResponse = (HttpWebResponse)endpointRequest.GetResponse();

獲取資源未返回的屬性

在你獲取一個資源時會返回許多屬性值，但是有些屬性你必須顯示地呼叫REST終結點進行獲取，就像CSOM中有些屬性需要顯示宣告來Load。比如從一個檔案資源獲取Author屬性：

http:// _<site url>_/_api/web/getfilebyserverrelativeurl('/ _<folder name>_/ _<file name>_')/author

使用REST介面進行寫入資料

你可以通過REST形式的HTTP請求更新SharePoint物件，和讀取資料類似。一個關鍵的不同是寫資料時需要使用POST請求，在更新SharePoint物件時，還要傳遞PUT或MERGE到X-HTTP-Method屬性中。

另一個在建立、更新和刪除SharePoint物件時需要的重要考慮是如果你使用的不是OAuth來授權你的請求的話，這些操作需要伺服器的請求表單摘要值作為請求頭中X-RequestDigest的值。你可以通過一個空白主體的POST請求到連結http://<siteurl>/_api/contextinfo來獲取這個值（d:FormDigestValue節點），下面的程式碼展示瞭如何通過C#請求contextinfo。

HttpWebRequest endpointRequest =
  (HttpWebRequest)HttpWebRequest.Create(
  "http://<site url>/_api/contextinfo");
endpointRequest.Method = "POST";
endpointRequest.Accept = "application/json;odata=verbose";
HttpWebResponse endpointResponse =
  (HttpWebResponse)endpointRequest.GetResponse();

如果你使用了指令碼跨域庫，SP.RequestExecutor會負責獲取和傳送摘要值。

如果你建立的是SharePoint託管的Add-in，你就不需要建立額外的HTTP請求來獲取表單摘要值了，你可以通過在SharePoint頁面上通過指令碼來獲取，如下程式碼，使用JQuery來建立一個列表。

jQuery.ajax({
        url: "http://<site url>/_api/web/lists",
        type: "POST",
        data:  JSON.stringify({ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true,
 'BaseTemplate': 100, 'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test' }
),
        headers: { 
            "accept": "application/json;odata=verbose",
            "content-type": "application/json;odata=verbose",
            "content-length": <length of post body>,
            "X-RequestDigest": $("#__REQUESTDIGEST").val()
        },
        success: doSuccess,
        error: doError
});

下面的示例展示瞭如何更新上面建立的列表，更新了列表的標題。

jQuery.ajax({
        url: "http://<site url>/_api/web/lists/GetByTitle('Test')",
        type: "POST",
        data: JSON.stringify({ '__metadata': { 'type': 'SP.List' }, 'Title': 'New title' }),
        headers: { 
            "X-HTTP-Method":"MERGE",
            "accept": "application/json;odata=verbose",
            "content-type": "application/json;odata=verbose",
            "content-length": <length of post body>,
            "X-RequestDigest": $("#__REQUESTDIGEST").val(),
            "IF-MATCH": "*"
        },
        success: doSuccess,
        error: doError
});

下面的程式碼展示瞭如何建立一個網站。

jQuery.ajax({
    url: "http://<site url>/_api/web/webinfos/add",
    type: "POST",
    data: JSON.stringify(
        {'parameters': {
            '__metadata':  {'type': 'SP.WebInfoCreationInformation' },
            'Url': 'RestSubWeb',
            'Title': 'RestSubWeb',
            'Description': 'REST created web',
            'Language':1033,
            'WebTemplate':'sts',
            'UseUniquePermissions':false}
        }
    ),
    headers: { 
        "accept": "application/json; odata=verbose", 
        "content-type":"application/json;odata=verbose",
        "content-length": <length of post body>,
        "X-RequestDigest": $("#__REQUESTDIGEST").val() 
    },
    success: doSuccess,
    error: doError
});