SharePoint REST API - 确定REST端点URL

博客地址：http://blog.csdn.net/FoxDave

SharePoint REST端点URI的结构

在你能够通过REST访问SharePoint资源之前，首先你要做的就是找出对应的URI端点，如果你对Client API熟悉，有些时候也可以参考Client API去猜测构建，例如。

客户端对象模型的方法：

List.GetByTitle(listname).GetItems()

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。下表是一个对应关系。

根据客户端对象模型来构建REST服务访问你想要访问的资源，如下表。

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"
   }
} 
}

你可以定义参数别名去请求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)就不行。

本篇就讲到这里。