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(不等于)。还有针对日期和时间的比较符,见表中解释。

       SharePoint REST 服务查询选项语法 

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

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

       

 

 

 

 

     

posted @ 2014-11-28 17:16  shaomeng  阅读(1096)  评论(0编辑  收藏  举报