码迷,mamicode.com
首页 > Windows程序 > 详细

[sharepoint]Rest api相关知识(转)

时间:2015-06-26 21:04:26      阅读:221      评论:0      收藏:0      [点我收藏+]

标签:

写在前面

最近又开始弄rest api了,通过sharepoint rest api获取站点信息,Items,fields非常方便,再结合OData查询,更是得心应手。这里记录学习的时候用到的知识点,以及查询的资料。

Sharepoint Rest 端点URI结构

在可以使用 REST 服务访问 SharePoint 资源之前,首先必须知道指向该资源的 URI 端点。只要可能,这些 REST 端点的 URI 就会准确地模仿 SharePoint 客户端对象模型中资源的 API 签名。例如:

客户端对象模型方法:            

List.GetByTitle(listname).GetItems()

REST 端点:            

http://server/site/_api/lists/getbytitle(‘listname‘)/items            

但是,在某些情况下,为了遵守 REST 或 OData 约定,端点 URI 会不同于相应的客户端对象模型签名。

下图显示 SharePoint REST URI 的通用语法结构。

SharePoint REST URI 语法结构

技术分享

SharePoint 资源的部分端点偏离了这种语法结构:

    • 需要复杂类型作为参数的方法。

      如果对应的客户端对象模型方法要求复杂类型作为参数传递,则 REST 端点可能偏离此语法构造说明 REST 限制。

    • 静态方法和属性。

      REST 端点偏离代表静态方法和属性的 URI 的语法结构。

确定 SharePoint 2013 REST 服务端点

若要为 SharePoint 资源构造 REST 端点,请按照以下步骤执行操作:

  1. 从 REST 服务引用开始:

    http://server/site/_api                

  2. 指定合适的入口点。例如:

    http://server/site/_api/web                

  3. 从入口点导航到您要访问的特定资源。这包括为与客户端对象模型中的方法对应的端点指定参数。例如:

    http://server/site/_api/web/lists/getbytitle(‘listname‘)                

引用端点 URI 中的 SharePoint 2013 REST 服务

使用 _api 来表示端点 URI 中的 SharePoint 2013 REST 服务。REST 服务属于 client.svc Web 服务的一部分。但是,要尽早构造 REST URI 以及缩短基础 REST URI 路径,REST 服务使用 _api 将显式引用 client.svc Web 服务的需求抽象出来。REST 服务将承认并接受引用 client.svc Web 服务的 URI。例如,您可以使用 http://server/site/_vti_bin/client.svc/web/lists 来代替 http://server/site/_api/web/lists。但是,使用 _api 是首选惯例。URL 限制为 256 个字符,因此,使用 _api 可以缩短基础 URI,以留下更多的字符用于构造剩余 URL。

指定 SharePoint 2013 REST 服务的入口点

REST 服务的主要入口点表示网站集合以及指定上下文的网站。这样,这些入口点与客户端对象模型中的 ClientContext.Site 属性和 ClientContext.Web 属性对应。

要访问特定的网站集合,请使用以下构造:

http://server/site/_api/site              

要访问特定的网站,请使用以下构造:

http://server/site/_api/web              

其中 server 表示服务器的名称,site 表示特定网站的名称或路径。

/site 和 /web 外,REST 服务包括几个其他访问点,通过这些访问点,开发人员可导航至特定功能。下表列出了部分访问点。

功能区域

访问点

网站

http://server/site/_api/site

Web

http://server/site/_api/web

用户配置文件

http:// server/site/_api/SP.UserProfiles.PeopleManager

搜索

http:// server/site/_api/search

发布

http:// server/site/_api/publishing

导航到您要访问的特定资源

从这里,通过遍历对象模型并使用用斜杠分隔的客户端对象模型中 API 的名称构造多个特定 REST 端点。下表显示客户端对象模型调用及等效 REST 端点示例。

客户端对象模型 API

REST 端点

ClientContext.Web.Lists

http://server/site/_api/web/lists

ClientContext.Web.Lists[guid]

http://server/site/_api/web/lists(‘guid’)

ClientContext.Web.Lists.GetByTitle("Title")

http://server/site/_api/web/lists/getbytitle(‘Title’)

终结点 URI 不区分大小写。例如,在上表中,使用 /getbytitle 指定 GetByTitle() 方法的 REST 等效项。

 指定 REST 端点 URI 中的参数

SharePoint 2013 扩展了 OData 规范,允许您使用括号来指定方法参数和索引值。这可防止包含多个名称相同参数的 URI 中的潜在混淆问题。例如,下面两个 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)            

下图显示了 SharePoint REST 参数语法。

SharePoint REST 参数语法

技术分享

些方法要求大的有效载荷作为参数。对于要与其对应客户端对象模型 API 保持功能平衡的 REST 端点,这些端点必须接受复杂类型作为参数。在这种情况下,REST 服务扩展了现有 OData 协议,允许这些 REST 端点接受单个复杂类型作为参数。这仅适用于 POST 操作,并且您必须根据 OData 标准以 Atom 格式或 JSON 格式传递复杂类型。

例如,ListCollection.Add 方法以 Microsoft.SharePoint.Client.ListCreationInformation 对象作为参数。要将列表添加到指定网站,请按如下方式构造相应的 REST 端点:

http://server/site/_api/web/lists/add              

然后,在请求正文中传递复杂类型,此处使用 JSON 进行格式设置。

{ "d" : {
   "results": {
     "__metadata": {
       "type": "SP.ListCreationInformation"
     }, 
     "CustomSchemaXml": "…large payload…/", 
     "Description": "desc", 
     "DocumentTemplateType": "1", 
     "TemplateType": "101", 
     "Title": "Announcements"
   }
} 
}

在 REST 服务调用中使用参数别名

您可以在 OData 中使用"参数别名"语义将参数传递到 SharePoint REST 端点。在参数别名中,用参数调用中的别名标识参数值,而实际值则在 URI 的查询字符串中指定。这允许您通过使用查询字符串支持多种类型的字符和一致的格式。

例如,以下两个 REST URI 为等效项:

直接指定参数值:              

http://server/site/_api/web/applyWebTemplate("STS#0")              

使用参数别名,并在 URI 的查询字符串中指定实际参数值:              

http://server/site/_api/web/applyWebTemplate(title=@template)?@template="STS#0"              

但是,SharePoint REST 服务不支持通过参数别名传递复杂类型。例如,以下 URI(参数别名中包含复杂类型)不受支持:

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

SharePoint REST 服务参数别名语法
技术分享

指定字典作为参数值

对于与以 Dictionary<String, String> 字典作为参数的方法相对应的 REST 端点,在查询字符串中将字典作为一组以逗号分隔的名称/值对传递。

Dictionary 参数 REST 服务语法
技术分享
Dictionary<String, object> 表示为多值对象,命名为 KeyedPropertyValue,并具有以下字符串属性:
  • Key 多值对象的键

  • Value 对象的值

  • ValueType 对象的值类型。对于映射到现有实体数据模型 (EDM) 类型的简单值类型,REST 服务返回相应的 EDM 类型字符串;例如,"Edm.String"。如果不是,则 REST 服务返回由 Type.ToString 功能返回的值类型。

在查询字符串中指定参数值

如果您的 REST URI 以方法调用结束,则可以使用查询字符串语法来指定方法的参数值。例如:

http://<server>/<site>/_api/web/applyWebTemplate?template="STS#0"              

下图显示查询字符串中参数的 REST 服务语法。

查询字符串中参数的 REST 服务语法
技术分享
指定静态方法和属性作为 REST 服务 URI

要构造与静态方法或属性对应的 URI,请使用 ECMAScript 对象模型中的对应 API 名称,该名称以命名空间声明开始并使用点记法 。例如,ECMAScript 客户端对象模型中的 SP.Utilities.Utility.getImageUrl(imageName) 将具有以下 REST 等效物:

http://server/site/_api/SP.Utilities.Utility.getImageUrl(‘imageName‘)            

但是,静态属性只能直接访问,不允许作为较大 URI 组成的一部分。例如,允许直接访问 REST 中的 SP.Utility.AssetsLibrary 方法,如下所示:

http://server/site/_api/SP.Utility.assetsLibrary/id            

但是,不允许将该资源位置用作更复杂 URI 的参数,如下面的示例所示:

http://server/site/_api/getList(~SP.Utility/assetsLibrary/id)            

下图显示 SharePoint REST 服务静态成员语法。

SharePoint REST 服务静态成员语法
技术分享
 

总结

rest api对我来说,刚开始是个小白,到现在用的越来越顺手,其中msdn对我来说帮了不少的忙,没空就看msdn,觉得这篇文章讲的还是比较清楚的,就收集到自己的博客中了。

参考文章:

https://msdn.microsoft.com/zh-cn/library/office/dn292556.aspx

https://msdn.microsoft.com/ZH-CN/library/dn551366.aspx

https://msdn.microsoft.com/zh-cn/library/office/fp142380(v=office.15).aspx

https://msdn.microsoft.com/zh-cn/library/gg309461.aspx

https://msdn.microsoft.com/en-us/library/jj860569.aspx

[sharepoint]Rest api相关知识(转)

标签:

原文地址:http://www.cnblogs.com/wolf-sun/p/4603199.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!