SharePoint REST API - 確定REST端點URL

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

SharePoint REST端點URI的結構

在你能夠通過REST訪問SharePoint資源之前，首先你要做的就是找出對應的URI端點，如果你對Client API熟悉，有些時候也可以參考Client API去猜測構建，例如。

客戶端物件模型的方法：

List.GetByTitle(listname).GetItems()

對應的REST端點URI為：

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

然而為了遵守REST和OData標準，REST端點和Client API不總是一致的。下圖展示了REST API的一般語法結構。

訪問某些SharePoint資源的API跟此語法結構不太一致，它們是：

>需要複雜型別引數的方法

>靜態方法和屬性

確定SharePoint REST服務的端點

構建一個訪問SharePoint資源的REST端點可以遵循下面的步驟：

1. 開始一段REST服務引用 http://server/site/_api

2. 指定適當的入口，如Web http://server/site/_api/web

3. 指定要訪問的具體資源，這通常跟客戶端物件模型是一致的 http://server/site/_api/web/lists/getbytitle('listname')

在你的URI端點中引用你的SharePoint REST服務

使用_api來表示SharePoint REST服務，REST服務是client.svc網路服務的一部分，REST是為了簡化所以改用_api來表示。也就是說，http://server/site/_vti_bin/client.svc/web/lists和http://server/site/_api/web/lists這兩種格式是都被支援的，但是推薦使用_api這種方式，因為URL有256個字元的限制。

指定SharePoint REST服務的入口

REST服務的主入口表示網站集合上下文物件（context）對應的網站，這跟ClientContext.Site和ClientContext.Web這兩個屬性一致。

如果要訪問一個指定的網站集，使用http://server/site/_api/site。如果要訪問一個指定的網站，使用http://server/site/_api/web。下表是一個對應關係。

Feature area	Access point
Site	http:// server/site/_api/site
Web	http:// server/site/_api/web
User Profile	http:// server/site/_api/SP.UserProfiles.PeopleManager
Search	http:// server/site/_api/search

訪問你想要訪問的指定資源

根據客戶端物件模型來構建REST服務訪問你想要訪問的資源，如下表。

**Client object model API **	REST endpoint
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')

在REST端點URI中指定引數

SharePoint擴充套件了OData規範使你能夠使用括號來指定方法的引數和索引下標值。這防止了在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)。

REST服務中的複雜引數型別

在客戶端物件模型的一些方法中需要大資料作為引數，REST也提供了這種能力，但是不在URL上，而是通過POST操作。例如，ListCollection.Add方法需要Microsoft.SharePoint.Client.ListCreationInformation作為引數，需要構建如下的請求：

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

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

在REST服務請求中使用別名

你可以定義引數別名去請求SharePoint REST，直接用示例說明。

直接請求的樣子：http://server/site/_api/web/applyWebTemplate("STS#0")

使用別名的樣子：http://server/site/_api/web/applyWebTemplate(title=@template)?@template="STS#0"

需要注意一下這種方式不支援複雜的引數，即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"}這樣的是不被支援的。

在REST服務URI中使用靜態方法和屬性

構建一個靜態方法或屬性的REST服務URI，可以使用與ECMAScript物件模型中一致的API名字，如http://server/site/_api/SP.Utilities.Utility.getImageUrl('imageName')。需要注意的是這種方式不能作為引數來傳遞而只能直接呼叫，舉個例子說明：

http://server/site/_api/SP.Utility.assetsLibrary/id是可以的，但是http://server/site/_api/getList(~SP.Utility/assetsLibrary/id)就不行。

本篇就講到這裡。