[sharepoint]Rest api相關知識（轉）

寫在前面

最近又開始弄rest api了，通過sharepoint rest api獲取站點信息，Items，fields非常方便，再結合OData查詢，更是得心應手。這里記錄學習的時候用到的知識點，以及查詢的資料。

Sharepoint Rest 端點URI結構

在可以使用 REST 服務訪問 SharePoint 資源之前，首先必須知道指向該資源的 URI 端點。只要可能，這些 REST 端點的 URI 就會准確地模仿 SharePoint 客戶端對象模型中資源的 API 簽名。例如：

客戶端對象模型方法：            

List.GetByTitle(listname).GetItems()

REST 端點：            

http://server/site/_api/lists/getbytitle('listname')/items            

但是，在某些情況下，為了遵守 REST 或 OData 約定，端點 URI 會不同於相應的客戶端對象模型簽名。

下圖顯示 SharePoint REST URI 的通用語法結構。

SharePoint REST URI 語法結構

SharePoint 資源的部分端點偏離了這種語法結構：

• • 需要復雜類型作為參數的方法。

    如果對應的客戶端對象模型方法要求復雜類型作為參數傳遞，則 REST 端點可能偏離此語法構造說明 REST 限制。

  • 靜態方法和屬性。

    REST 端點偏離代表靜態方法和屬性的 URI 的語法結構。

確定 SharePoint 2013 REST 服務端點

若要為 SharePoint 資源構造 REST 端點，請按照以下步驟執行操作：

1. 從 REST 服務引用開始：

   http://server/site/_api                

2. 指定合適的入口點。例如：

   http://server/site/_api/web                

3. 從入口點導航到您要訪問的特定資源。這包括為與客戶端對象模型中的方法對應的端點指定參數。例如：

   http://server/site/_api/web/lists/getbytitle('listname')                

引用端點 URI 中的 SharePoint 2013 REST 服務

使用 _api 來表示端點 URI 中的 SharePoint 2013 REST 服務。REST 服務屬於 client.svc Web 服務的一部分。但是，要盡早構造 REST URI 以及縮短基礎 REST URI 路徑，REST 服務使用 _api 將顯式引用 client.svc Web 服務的需求抽象出來。REST 服務將承認並接受引用 client.svc Web 服務的 URI。例如，您可以使用 http://server/site/_vti_bin/client.svc/web/lists 來代替 http://server/site/_api/web/lists。但是，使用 _api 是首選慣例。URL 限制為 256 個字符，因此，使用 _api 可以縮短基礎 URI，以留下更多的字符用於構造剩余 URL。

指定 SharePoint 2013 REST 服務的入口點

REST 服務的主要入口點表示網站集合以及指定上下文的網站。這樣，這些入口點與客戶端對象模型中的 ClientContext.Site 屬性和 ClientContext.Web 屬性對應。

要訪問特定的網站集合，請使用以下構造：

http://server/site/_api/site              

要訪問特定的網站，請使用以下構造：

http://server/site/_api/web              

其中 server 表示服務器的名稱，site 表示特定網站的名稱或路徑。

除 /site 和 /web 外，REST 服務包括幾個其他訪問點，通過這些訪問點，開發人員可導航至特定功能。下表列出了部分訪問點。

功能區域	訪問點
網站	http://server/site/_api/site
Web	http://server/site/_api/web
用戶配置文件	http:// server/site/_api/SP.UserProfiles.PeopleManager
搜索	http:// server/site/_api/search
發布	http:// server/site/_api/publishing

導航到您要訪問的特定資源

從這里，通過遍歷對象模型並使用用斜杠分隔的客戶端對象模型中 API 的名稱構造多個特定 REST 端點。下表顯示客戶端對象模型調用及等效 REST 端點示例。

客戶端對象模型 API	REST 端點
ClientContext.Web.Lists	http://server/site/_api/web/lists
ClientContext.Web.Lists[guid]	http://server/site/_api/web/lists(‘guid’)
ClientContext.Web.Lists.GetByTitle("Title")	http://server/site/_api/web/lists/getbytitle(‘Title’)

終結點 URI 不區分大小寫。例如，在上表中，使用 /getbytitle 指定 GetByTitle() 方法的 REST 等效項。

 指定 REST 端點 URI 中的參數

SharePoint 2013 擴展了 OData 規范，允許您使用括號來指定方法參數和索引值。這可防止包含多個名稱相同參數的 URI 中的潛在混淆問題。例如，下面兩個 URI 包含名稱相同的參數：

http://server/site/_api/web/lists/getByTitle('Announcements')/fields/getByTitle('Description')            

http://server/site/_api/web/lists('<guid>')/fields/getById('<guid>')            

要指定多個參數，請將參數作為名稱/值對包含在內，並用逗號將參數分隔。例如：

http://server/site/_api/web/getAvailableWebTemplates(lcid=1033, includeCrossLanguage=true)            

下圖顯示了 SharePoint REST 參數語法。

SharePoint REST 參數語法

些方法要求大的有效載荷作為參數。對於要與其對應客戶端對象模型 API 保持功能平衡的 REST 端點，這些端點必須接受復雜類型作為參數。在這種情況下，REST 服務擴展了現有 OData 協議，允許這些 REST 端點接受單個復雜類型作為參數。這僅適用於 POST 操作，並且您必須根據 OData 標准以 Atom 格式或 JSON 格式傳遞復雜類型。

例如，ListCollection.Add 方法以 Microsoft.SharePoint.Client.ListCreationInformation 對象作為參數。要將列表添加到指定網站，請按如下方式構造相應的 REST 端點：

http://server/site/_api/web/lists/add              

然后，在請求正文中傳遞復雜類型，此處使用 JSON 進行格式設置。

{ "d" : {
   "results": {
     "__metadata": {
       "type": "SP.ListCreationInformation"
     }, 
     "CustomSchemaXml": "…large payload…/", 
     "Description": "desc", 
     "DocumentTemplateType": "1", 
     "TemplateType": "101", 
     "Title": "Announcements"
   }
} 
}

在 REST 服務調用中使用參數別名

您可以在 OData 中使用"參數別名"語義將參數傳遞到 SharePoint REST 端點。在參數別名中，用參數調用中的別名標識參數值，而實際值則在 URI 的查詢字符串中指定。這允許您通過使用查詢字符串支持多種類型的字符和一致的格式。

例如，以下兩個 REST URI 為等效項：

直接指定參數值：              

http://server/site/_api/web/applyWebTemplate("STS#0")              

使用參數別名，並在 URI 的查詢字符串中指定實際參數值：              

http://server/site/_api/web/applyWebTemplate(title=@template)?@template="STS#0"              

但是，SharePoint REST 服務不支持通過參數別名傳遞復雜類型。例如，以下 URI（參數別名中包含復雜類型）不受支持：

http://server/site/_api/userProfiles/People(7)/GetWorkplace(@address)?@address={"__metadata":{"type: "ODataDemo.Address"},"Street":"NE 228th", "City":"Sammamish","State":"WA","ZipCode":"98074","Country": "USA"}              

SharePoint REST 服務參數別名語法

指定字典作為參數值

對於與以 Dictionary<String, String> 字典作為參數的方法相對應的 REST 端點，在查詢字符串中將字典作為一組以逗號分隔的名稱/值對傳遞。

Dictionary 參數 REST 服務語法

Dictionary<String, object> 表示為多值對象，命名為 KeyedPropertyValue，並具有以下字符串屬性：

• Key 多值對象的鍵

• Value 對象的值

• ValueType 對象的值類型。對於映射到現有實體數據模型 (EDM) 類型的簡單值類型，REST 服務返回相應的 EDM 類型字符串；例如，"Edm.String"。如果不是，則 REST 服務返回由 Type.ToString 功能返回的值類型。

在查詢字符串中指定參數值

如果您的 REST URI 以方法調用結束，則可以使用查詢字符串語法來指定方法的參數值。例如：

http://<server>/<site>/_api/web/applyWebTemplate?template="STS#0"              

下圖顯示查詢字符串中參數的 REST 服務語法。

查詢字符串中參數的 REST 服務語法

指定靜態方法和屬性作為 REST 服務 URI

要構造與靜態方法或屬性對應的 URI，請使用 ECMAScript 對象模型中的對應 API 名稱，該名稱以命名空間聲明開始並使用點記法 。例如，ECMAScript 客戶端對象模型中的 SP.Utilities.Utility.getImageUrl(imageName) 將具有以下 REST 等效物：

http://server/site/_api/SP.Utilities.Utility.getImageUrl('imageName')            

但是，靜態屬性只能直接訪問，不允許作為較大 URI 組成的一部分。例如，允許直接訪問 REST 中的 SP.Utility.AssetsLibrary 方法，如下所示：

http://server/site/_api/SP.Utility.assetsLibrary/id            

但是，不允許將該資源位置用作更復雜 URI 的參數，如下面的示例所示：

http://server/site/_api/getList(~SP.Utility/assetsLibrary/id)            

下圖顯示 SharePoint REST 服務靜態成員語法。

SharePoint REST 服務靜態成員語法

 

 

總結

rest api對我來說，剛開始是個小白，到現在用的越來越順手，其中msdn對我來說幫了不少的忙，沒空就看msdn，覺得這篇文章講的還是比較清楚的，就收集到自己的博客中了。

參考文章：

https://msdn.microsoft.com/zh-cn/library/office/dn292556.aspx

https://msdn.microsoft.com/ZH-CN/library/dn551366.aspx

https://msdn.microsoft.com/zh-cn/library/office/fp142380(v=office.15).aspx

https://msdn.microsoft.com/zh-cn/library/gg309461.aspx

https://msdn.microsoft.com/en-us/library/jj860569.aspx