Windows 商店应用中使用 SharePoint REST API

前面一篇我们介绍了 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://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 有所帮助，谢谢。