确定 SharePoint REST 服务终结点 URI

提示

在开始之前，请查看以下资源：

了解 SharePoint REST 服务导航 REST 服务中表示的 SharePoint 数据结构

• 使用 SharePoint REST 服务进行编程

SharePoint REST 终结点 URI 结构

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

CSOM

var items = List.GetByTitle(listname).GetItems();

http

GET https://{site_url}/_api/lists/getbytitle('{list_name}')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

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

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

SharePoint REST URI 语法结构**

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

• 需要复杂类型作为参数的方法。 如果对应的客户端对象模型方法要求复杂类型作为参数传递，则 REST 端点可能偏离此语法构造说明 REST 限制。
• 静态方法和属性。 REST 终结点偏离代表静态方法和属性的 URI 的语法结构。

确定 SharePoint REST 服务终结点

若要为 SharePoint 资源构造 REST 终结点，请按照以下步骤执行操作：

1. 从 REST 服务引用开始：

   https://{site_url}/_api

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

   https://{site_url}/_api/web

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

   https://{site_url}/_api/web/lists/getbytitle('{list_name}')

引用终结点 URI 中的 SharePoint REST 服务

使用 _api 表示终结点 URI 中的 SharePoint REST 服务。 REST 服务是 client.svc Web 服务的一部分。 但是，为了简化 REST URI 构造并缩短基本 REST URI 路径，REST 服务使用 _api 剔除显式引用 client.svc Web 服务的需求。

REST 服务仍可识别和接受引用 client.svc web 服务的 URI。 例如，可使用 https://{site_url}/_vti_bin/client.svc/web/lists 而不是 https://{site_url}/_api/web/lists。 但是，首选约定是使用 _api。 URL 的字符数限制为 256 个，因此使用 _api 缩短基本 URI，留出更多字符用于构造 URL 的其余部分。

指定 SharePoint REST 服务的入口点

REST 服务的主入口点表示网站集和指定上下文的网站。 由此，这些入口点就对应于客户端对象模型中的 ClientContext.Site 属性和 ClientContext.Web 属性。

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

https://{site_url}/_api/site

请使用以下构造访问特定网站：

https://{site_url}/_api/web

除了 /site 和 /web，REST 服务还包括几个其他访问点，这些访问点可帮助开发人员导航到特定功能。 下表列出了部分访问点。

功能区	访问点
网站	https://{site_url}/_api/site
Web	https://{site_url}/_api/web
用户配置文件	https://{site_url}/_api/SP.UserProfiles.PeopleManager
搜索	https://{site_url}/_api/search

导航到要访问的特定资源

在这里，可以遍历对象模型，并使用客户端对象模型中的 API 名称（以正斜线 (/) 分隔），构造多个特定 REST 终结点。 下表列出了客户端对象模型调用示例和同等 REST 终结点。

客户端对象模型 API	REST 终结点
ClientContext.Web.Lists	https://{site_url}/_api/web/lists
ClientContext.Web.Lists[guid]	https://{site_url}/_api/web/lists('<guid>')
ClientContext.Web.Lists.GetByTitle("Title")	https://{site_url}/_api/web/lists/getbytitle('<Title>')

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

指定 REST 终结点 URI 中的参数

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

https://{site_url}/_api/web/lists/getByTitle('Announcements')/fields/getByTitle('Description')

https://{site_url}/_api/web/lists('{list_guid}')/fields/getById('{guid}')

要指定多个参数，请将参数作为名称/值对包含在内，并用逗号将参数分隔。 例如：

https://{site_url}/_api/web/getAvailableWebTemplates(lcid=1033, includeCrossLanguage=true)

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

SharePoint REST 参数语法

复杂类型用作 REST 服务的参数

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

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

POST https://{site_url}/_api/web/lists/add
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}

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

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

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

例如，以下两个 REST URI 为等效项：

直接指定参数值：

https://{site_url}/_api/web/applyWebTemplate("STS#0")

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

https://{site_url}/_api/web/applyWebTemplate(title=@template)?@template="STS#0"

但是，SharePoint REST 服务不支持通过参数别名传递复杂类型。 例如，以下 URI（参数别名中包含复杂类型）不受支持：

https://{site_url}/_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 以方法调用结束，则可以使用查询字符串语法来指定方法的参数值。 例如：

https://{site_url}/_api/web/applyWebTemplate?template="STS#0"

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

查询字符串中参数的 REST 服务语法

指定静态方法和属性作为 REST 服务 URI

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

https://{site_url}/_api/SP.Utilities.Utility.getImageUrl('imageName')

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

https://{site_url}/_api/SP.Utility.assetsLibrary/id

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

https://{site_url}/_api/getList(~SP.Utility/assetsLibrary/id)

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

SharePoint REST 服务静态成员语法

如果要对从端点请求的数据进行选择、筛选和排序，SharePoint REST 服务支持许多不同的 OData 查询字符串运算符。 有关详细信息，请参阅在 SharePoint REST 请求中使用 OData 查询操作

另请参阅

• 了解 SharePoint REST 服务
• 通过 REST 服务使用 ETag 值获取文档列表项的版本控制
• OData 资源
• 开发 SharePoint 加载项