Windows 商店应用中使用 SharePoint REST API_.NET_编程开发_程序员俱乐部

前面一篇我们介绍了 Office 365 REST API 的官方工具的使用，本篇我们来看一下 SharePoint REST API 本身的描述、结构和使用方法，以及一些使用经验。

首先来看看SharePoint REST API 的概述：

      REST API 服务是在 SharePoint 2013 中被引入的，官方认为 REST API 服务可以媲美于现有的 SharePoint 客户端对象模型。开发人员可以使用任何支持 REST Web 请求的技术（C#，javascript，java，oc 等等）以远程方式与 SharePoint 数据进行交互。这也就意味着，开发人员可以使用 REST Web技术和标准开放数据协议（OData）语法从其 SharePoint 相关应用程序、解决方案和客户端应用程序执行 CRUD 操作。而针对远程 Web 或移动应用，必须先获得访问权限，才能使用 SharePoint 数据资源。

     在 REST API 出现之前，我们需要通过 client.svc 这个 WCF 服务来请求 SharePoint 的列表数据，而且仅限于获取数据。数据的修改并没有在这个服务中体现。而通过 REST API，我们可以完成前面提到的 CRUD 操作：使用OData 标准构造可实现 REST 的 HTTP 请求，对应到相应的请求方法，就可以对该资源进行读取或操作了。例如使用 GET 方法取得数据，使用 POST 方法来创建数据，使用 PUT 或 MERGE 方法来更新数据，使用 DELETE 方法来删除数据。

      REST API 默认会返回 Atom 格式的数据，不过我们也可以根据需求设定返回 JSON 格式的数据。我个人更喜欢处理 JSON 格式，JSON 数据转换为 C# 的对象，有一个很棒的网站：http://json2csharp.com/。通过这个网站，我们可以把 JSON 数据直接转换为 C# 对象，节省了很多编写 C# 基础代码的时间。

接下来我们来看看 REST API 的结构组成：

      端点的基本URL是：https://server/site/_api ,它是所有 SharePoint REST API 的基础，其中 server 代表服务器的名称，site 代表特定网站的名称或者路径。

      如果要访问特定的网站集，URL是：https://server/site/_api/site，如果要访问特定的网站，URL则是：https://server/site/_api/web 。这两种是最常用的 API ，还有几种 API 能实现一些特定的功能，如：使用搜索服务：https://server/site/_api/search，访问用户配置文件：http://class="parameter">server/site/_api/SP.UserProfiles.PeopleManager 等。

      下面我们以特定网站为例，来看一下 REST API 能完成哪些常见操作：

      （1）对列表和列表项的操作

       列表：

       URL：http://<网站 URL>/web/lists(guid'<列表 ID>') 或 http://<网站 URL>/web/lists/getbytitle('title of list')

       列表项集合：

       URL：http://<网站 URL>/web/lists(guid'<列表 ID>') /items 或 http://<网站 URL>/web/lists/getbytitle('title of list')/items

      指定 ID 的列表项：

      URL：http://<网站 URL>/web/lists(guid'<列表 ID>') /items(item id) 或 http://<网站 URL>/web/lists/getbytitle('title of list')/items(item id)

       如上 API 地址所示，我们可以通过List 本身的 GUID 或者 Title 来获取List，或者List的项集合的数据。当需要向列表中插入新项时，我们需要使用列表项集合 API，使用 POST 方法插入数据。而需要修改列表中某一项时，则需要使用指定列表项 API，使用 MERGE 方法来更新数据。

       而涉及到数据修改时，我们需要把方法类型，如 POST，MERGE 等作为X-HTTP_Method 键的值添加到请求标头中。而且需要将请求窗体摘要值作为 X-RequestDigest 的值传递进去。该值的获取方式是：向 http://网站URL/_api/contextinfo
发送具有空正文的 POST 请求，并在 contextinfo 终结点返回的 XML 中提取 d:FormDigestValue 节点的值。还有就是标头中的 IF-MATCH 键的值，需要赋值为列表或列表项的 etag 值。如果赋值为 “*”，则不会考虑并发问题。

       另外关于数据操作是需要 POST 的内容：

       更新时，必须包含 __metadata:type 和需要更新的字段。其他不需要更新的字段可以不加入。删除时，URL指向该条记录即可。添加时，URL指向记录集合，POST内容应包含__metadata:type 和需要插入的必填字段

      （2）对文件和文件夹的操作

       文件：

       URL：http://<网站 URL>/_api/web/getfilebyserverrelativeurl('/<文件夹名称>/<文件名称>')

       文件列表：

       URL：http://<网站 URL>/_api/web/getfolderbyserverrelativeurl('/<文件夹名称>')/files

       文件夹：

       URL：http://<网站 URL>/_api/web/getfolderbyserverrelativeurl('/<文件夹名称>')

       通过以上 API 操作，我们可以完成文件和文件夹的读取，上传和修改等操作。

       当需要向文档库插入文档时，URL 是：http://<site url>/_api/web/GetFolderByServerRelativeUrl('/Shared Documents')/Files/add(url='a.txt',overwrite=true)，这样，我们就把文件以 a.txt 为存放名称插入到了 Shared Documents 文档库中。而文档内容的上传过程是：文件读取为 Stream，放入 POST 内容中。文件还有其他很多中操作方式，如更新，签出，签入，删除等。

      （3）对用户、组和角色的操作

       组：

       URL：http://<网站 URL>/_api/web/sitegroups(<组 ID>)

       用户：

       URL：http://<网站 URL>/_api/web/siteusers(@v)?@v='<登录名>'

       角色：

       URL：http://<网站 URL>/_api/web/roledefinitions(<角色定义 ID>)

      （4）对用户配置文件的操作

       URL：http://<网站 url>/_api/sp.userprofiles.peoplemanager

      （5）对字段的操作

       URL：http://<网站 url>/_api/web/fields('<字段 id>') 或 http://<网站 url>/_api/web/lists(guid'<列表 id>')/fields('<字段 id>')

       上面我们介绍了列表，文件夹等类型 API 的地址构造，接下来我们看看这些请求地址中允许的查询参数都有哪些：       

       （1）$select 参数

       如 SQL 中 Select 的使用方法，这里的 $select 也是确定请求返回的结果中需要包含哪些字段，使用方法是：_api/web/lists/getByTitle('Books')/items?$select=Author,Title,ISBN，这样我们就会在取得Books这个列表时，只获取作者，书名和ISBN三个有效字段。

       （2）$filter 参数

       如 SQL 中 Where 的使用方法，这里的 $filter 是用来筛选数据的筛选条件，使用方法是：_api/web/lists/getByTitle('Books')/items?$filter=Author eq 'Mark Twain'，这样我们就能取到 Books 列表中，Author 为 Mark Twain 的数据。

       （3）$expand 参数

       这个参数用于指定返回联接列表中的哪些投射字段。使用方法是：_api/web/lists/getByTitle('Books')/items?$select=Title,PublishedBy/Name&$expand=PublishedBy，这里的投射字段是 PublishedBy。

       （4）$top 参数

       这个参数用户指定返回结果集中的前N项，使用方法是：_api/web/lists/getByTitle('Books')/items?$top=2，这样我们就会返回这个结果集中的前两项（如不足两项则返回全部数据）。

       （5）$skip 参数

       这个参数用于在结果集中跳过指定数量的项，而返回剩余的项。使用方法是：_api/web/lists/getByTitle('Books')/items?$skip=2，这样我们就会在返回结果中跳过前两项而返回其余的项，如结果不足两项，则返回空结果集。

       （6）$orderby 参数

       这个参数用于对结果集进行排序，如 SQL 中使用方法，分为升序和降序两种方式，以 asc 和 desc 关键字来标识。使用方法是：_api/web/lists/getByTitle('Books')/items?$orderby=ID desc。这样我们返回的结果集，就会以 ID 为标准来降序排列。 

       下面这张表，涵盖了 SharePoint REST API 中几乎所有的查询条件和数字、字符等的比较关键字。例如 $filter=Author eq 'Mark Twain'，就是筛选 Author 等于 Mark Twain 的项，而 Author ne 'Mark Twain'，则是筛选不等的项。这是针对字符串的比较操作，而针对数字的则包括  lt（小于）、le（小于等于）、gt（大于）、ge（大于等于）、eq（等于）和 ne（不等于）。还有针对日期和时间的比较符，见表中解释。

       最后还涉及到一个授权的问题，如前面所说，远程访问都需要先授权才能访问资源。我们可以通过 OAuth 授权的方式来完成应用授权和身份验证。将获得的 OAuth 访问令牌加入到请求标头中。这里我们不做详细介绍了。关于 API本身的使用过程，和其他 API 没什么差异，这里就不做详细介绍了。就是一个发出请求，获得返回结果（Atom或JSON），然后解析结果的过程。

       这样我们就把 SharePoint REST API 的构成和基本的使用方法介绍完了，希望对大家在 Windows 商店应用中使用 SharePoint REST API 有所帮助，谢谢。