SharePoint 2013的REST编程基础

1. SharePoint 2013对REST编程的支持

自从SharePoint2013开始， SharePoint开始了对REST 编程的支持，这样除了.NET , Silverlight， Powershell之外， 又多了一种可以和SharePoint Server进行CSOM编程的方式。那么，问题来了：什么是REST呢？什么是ODATA？为什么这么多产品都开始支持这个了？

2. 什么是REST & ODATA?

如果这个世界上只有一家IT公司就好了，这样就不需要REST了 :) 但是很显然，这是不可能的。不同IT公司有自己提出的技术标准及解决方案。以Microsoft为例，其实现分布式处理的技术和解决方案发展历程如下：COM -> DCOM -> COM+ ,跨入.NET时代，又出现了 Enterprise Component -> Web Service -> Web Service Enhancemant -> WCF ...

可以看到，仅仅一家公司，其提出的技术和解决方案就如此之多。在加上IBM, Google等等大鳄，就形成了各自为政，群雄混战的局面。这样的解决就是:在各自的系统和技术内，大家各自搞自己的。很显然这是不符合时代发展的 :) 比如没有任何一家公司，只用某一家IT公司的解决方案。不同公司的系统之间，也需要互相通讯。

那怎么解决这个问题呢？大家握手言和吧：制定一个基于HTTP协议的标准。HTTP协议是目前为止，最通用和成功的协议。如果某个公司说我就是不遵守HTTP协议，那他就没法转了。 因此，只要大家遵循这个标准，系统之间都可以互相通信。如果利用Microsoft的技术开发了一个服务，只要这个服务遵循这个标准，采用IBM技术的客户也可以consume这个服务，那不是很好吗？ 因此这就是REST服务出现的现实需要。

言归正传，什么是REST 服务呢？

REST的全称是： Representational state transfer （有点绕口 ：））, 她的基本思想是:可以通过基于HTTP协议发出的不同 操作：Create, Read, Update, and Delete (CRUD)， 来实现对数据的操作。其有三大基本特征：

1） 客户端- 服务端：

所以数据都存储在服务端，客户端不知道也无需知道服务端如何处理的，只需要发送一个HTTP请求。

2) 无状态：

这个比较抽象。打个比方：

你申明一个proxy去调用服务器端的求和函数 proxy.sum(1,2) ,服务器端返回3给客户端。 当你再次调用proxy.sum(3,4)的时候，如果是无状态的话，其是不会记住你上次操作的结果的，也就是其会返回7；但是如果是有状态的操作，其会记录上一次调用的结果，并把这次结果累加再返回给客户端，也就是3+7=10.

3）可缓存的

4）分层的

5） 统一的接口

以下是关于REST的Wiki解释:

http://en.wikipedia.org/wiki/Representational_state_transfer

3. 如何实现一个RESTful服务

实现一个RESTful服务的方案有很多。以Microsoft的.NET解决方案为例， WCF3.5就开始了对REST服务的支持。你可以用WCF轻松创建一个 WCF REST API服务供其它客户端consume.

有关如何通过WCF 实现一个REST服务，可以参考下面的文档：

https://msdn.microsoft.com/en-us/magazine/dd315413.aspx

4 如何过滤和选择数据

如何让服务器返回自己真正想要的数据呢？ 其实ODATA提供了丰富的数据过滤和选择操作：

1）$filter : 过滤数据

2） $select : 选择需要的字段

3) $expand: 扩展返回的属性

4) $orderby:排序

5) $top:返回前N条数据

5. SharePoint 2013对REST服务的支持

SharePoint 2013 实现了REST服务的支持，这样我们又多了一种途径可以访问SharePoint了。实际上SharePoint的REST服务是一个通过叫做client.svc的WCF REST服务来实现的。其URL为：https://sharepointserver/_vti_bin/client.svc

1) SharePoint 2013的REST服务部署的路径如下：

https://servername/sitename/_api/....

实际上上面这个地址只是其原始服务的一个别名（alias), 毕竟打出完成的client.svc有点丑陋哦。

比如：

https://winstononline.sharepoint.com/_api/...

https://winstononline.sharepoint.com/sites/spdev/...

2) SharePoint 2013支持的命名空间：

要对SharePoint 2013发出一个REST请求，必须指明你所要访问的namespace。支持的namespace包括：

a) _api/web

b) _api/site

c) _api/search

d) _api/publishing

例如： 我想返回一个叫做Doctest的list里面ID为3的item，并且只返回ID字段：

http://winstononline.sharepoint.com/_api/web/lists/Doctest/items?$filter=ID eq 3 & $select=ID

又如：

https://winstononline.sharepoint.com/_api/web/lists/Doctest/items?$select=ID & $orderby=ID

1. <?xml version="1.0" encoding="utf-8" ?>
2.  
3. - <feed xml:base="https://winstononline.sharepoint.com/_api/" xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml">
4.  
5. <id>b3c0e660-6937-4da9-b1cf-c1bd6613be1a</id>
6.  
7. <title />
8.  
9. <updated>2015-02-04T07:22:31Z</updated>
10.  
11. - <entry m:etag=""3"">
12.  
13. <id>bccd25b6-c6cf-4748-a75b-aca5b6826fe8</id>
14.  
15. <category term="SP.Data.DoctestItem" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
16.  
17. <link rel="edit" href="Web/Lists(guid'906b7bcc-bd4f-4d8c-9e46-6e01b5579d5f')/Items(1)" />
18.  
19. <title />
20.  
21. <updated>2015-02-04T07:22:31Z</updated>
22.  
23. - <author>
24.  
25. <name />
26.  
27. </author>
28.  
29. - <content type="application/xml">
30.  
31. - <m:properties>
32.  
33. <d:Id m:type="Edm.Int32">1</d:Id>
34.  
35. <d:ID m:type="Edm.Int32">1</d:ID>
36.  
37. </m:properties>
38.  
39. </content>
40.  
41. </entry>
42.  
43. - <entry m:etag=""4"">
44.  
45. <id>7604db11-97fa-4433-b652-51eb70b013d9</id>
46.  
47. <category term="SP.Data.DoctestItem" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
48.  
49. <link rel="edit" href="Web/Lists(guid'906b7bcc-bd4f-4d8c-9e46-6e01b5579d5f')/Items(2)" />
50.  
51. <title />
52.  
53. <updated>2015-02-04T07:22:31Z</updated>
54.  
55. - <author>
56.  
57. <name />
58.  
59. </author>
60.  
61. - <content type="application/xml">
62.  
63. - <m:properties>
64.  
65. <d:Id m:type="Edm.Int32">2</d:Id>
66.  
67. <d:ID m:type="Edm.Int32">2</d:ID>
68.  
69. </m:properties>
70.  
71. </content>
72.  
73. </entry>
74.  
75. - <entry m:etag=""2"">
76.  
77. <id>ec2a5b46-ae8f-4334-8a85-9a777660021c</id>
78.  
79. <category term="SP.Data.DoctestItem" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
80.  
81. <link rel="edit" href="Web/Lists(guid'906b7bcc-bd4f-4d8c-9e46-6e01b5579d5f')/Items(3)" />
82.  
83. <title />
84.  
85. <updated>2015-02-04T07:22:31Z</updated>
86.  
87. - <author>
88.  
89. <name />
90.  
91. </author>
92.  
93. - <content type="application/xml">
94.  
95. - <m:properties>
96.  
97. <d:Id m:type="Edm.Int32">3</d:Id>
98.  
99. <d:ID m:type="Edm.Int32">3</d:ID>
100.  
101. </m:properties>
102.  
103. </content>
104.  
105. </entry>
106.  
107. </feed>

6. SharePoint客户端技术对REST服务的支持

如果采用上面发送REST请求的方法来和SharePoint进行交互，可以很容易的执行各种操作。但是唯一的确定是没法进行批量化的操作。为了让客户端采用javascript来调用SharePoint REST的时候更加友好和强大，SharePoint提供了2个javascript类库，分别为sp.js和sp.runtime.js, 其位于_layouts/15/###.js下。与开发者相关的，更多的是sp.js里面的定义。这样所有的REST操作都被封装在sp.js里定义的API 里面，显得更加友好。

下面是通过Napa创建的一个default sharePoint App, 里面就用到了SP.js。

1. <%-- The following 4 lines are ASP.NET directives needed when using SharePoint components --%>
2. <%@ Page Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" MasterPageFile="~masterurl/default.master" Language="C#" %>
3. <%@ Register TagPrefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
4. <%@ Register TagPrefix="Utilities" Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
5. <%@ Register TagPrefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
6.  
7. <%-- The markup and script in the following Content element will be placed in the <head> of the page --%>
8. <asp:Content ContentPlaceHolderID="PlaceHolderAdditionalPageHead" runat="server">
9. <script type="text/javascript" src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.9.1.min.js"></script>
10. <script type="text/javascript" src="/_layouts/15/sp.runtime.js"></script>
11. <script type="text/javascript" src="/_layouts/15/sp.js"></script>
12.  
13. <!-- Add your CSS styles to the following file -->
14. <link rel="Stylesheet" type="text/css" href="../Content/App.css" />
15.  
16. <!-- Add your JavaScript to the following file -->
17. <script type="text/javascript" src="../Scripts/App.js"></script>
18. </asp:Content>
19.  
20. <%-- The markup in the following Content element will be placed in the TitleArea of the page --%>
21. <asp:Content ContentPlaceHolderID="PlaceHolderPageTitleInTitleArea" runat="server">
22. Page Title
23. </asp:Content>
24.  
25. <%-- The markup and script in the following Content element will be placed in the <body> of the page --%>
26. <asp:Content ContentPlaceHolderID="PlaceHolderMain" runat="server">
27.  
28. <div>
29. <p id="message">
30. <!-- The following content will be replaced with the user name when you run the app - see App.js -->
31. initializing...
32. </p>
33. </div>
34.  
35. </asp:Content>
36.  
37. <!--app.js-->
38.  
39. var context = SP.ClientContext.get_current();
40. var user = context.get_web().get_currentUser();
41.  
42. (function () {
43.  
44. // This code runs when the DOM is ready and creates a context object which is
45. // needed to use the SharePoint object model
46. $(document).ready(function () {
47. getUserName();
48. });
49.  
50. // This function prepares, loads, and then executes a SharePoint query to get
51. // the current users information
52. function getUserName() {
53. context.load(user);
54. context.executeQueryAsync(onGetUserNameSuccess, onGetUserNameFail);
55. }
56.  
57. // This function is executed if the above call is successful
58. // It replaces the contents of the 'message' element with the user name
59. function onGetUserNameSuccess() {
60. $('#message').text('Hello ' + user.get_title() +"This is my first Napa app");
61. }
62.  
63. // This function is executed if the above call fails
64. function onGetUserNameFail(sender, args) {
65. alert('Failed to get user name. Error:' + args.get_message());
66. }
67.  
68. })();
69.  
70. function getParameterByName(name)
71. {
72.  
73. }

6. 调用SharePoint REST服务示例