确定 SharePoint REST 服务终结点 URIDetermine SharePoint REST service endpoint URIs

SharePoint REST 终结点 URI 结构SharePoint REST endpoint URI structure

在可以使用 REST 服务访问 SharePoint 资源之前,首先必须知道指向该资源的 URI 端点。只要可能,这些 REST 端点的 URI 就会准确地模仿 SharePoint 客户端对象模型中资源的 API 签名。例如:Before you can access a SharePoint resource using the REST service, you first have to figure out the URI endpoint that points to that resource. Whenever possible, the URI for these REST endpoints closely mimics the API signature of the resource in the SharePoint client object model. For example:

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

但是,在某些情况下,为了遵守 REST 或 OData 约定,端点 URI 会不同于相应的客户端对象模型签名。In some cases, however, the endpoint URI differs from the corresponding client object model signature, in order to comply with REST or OData conventions.

下图显示 SharePoint REST URI 的通用语法结构。The following figure shows the general syntax structure of SharePoint REST URIs.

SharePoint REST URI 语法结构**SharePoint REST URI syntax structure**

SharePoint REST 请求语法

SharePoint 资源的部分终结点偏离了这种语法结构:Some endpoints for SharePoint resources deviate from this syntax structure:

  • 需要复杂类型作为参数的方法。Methods that require complex types as parameters. 如果对应的客户端对象模型方法要求复杂类型作为参数传递,则 REST 端点可能偏离此语法构造说明 REST 限制。If the corresponding client object model method requires that complex types are passed as parameters, the REST endpoint may deviate from this syntax construction to account for REST limitations.
  • 静态方法和属性。Static methods and properties. REST 终结点偏离代表静态方法和属性的 URI 的语法结构。REST endpoints deviate from this syntax structure for URIs that represent static methods and properties.

确定 SharePoint REST 服务终结点Determine SharePoint REST service endpoints

若要为 SharePoint 资源构造 REST 终结点,请按照以下步骤执行操作:To construct a REST endpoint for a SharePoint resource, follow these steps:

  1. 从 REST 服务引用开始:Start with the REST service reference:

    https://{site_url}/_api

  2. 指定合适的入口点。例如:Specify the appropriate entry point. For example:

    https://{site_url}/_api/web

  3. 从入口点导航到您要访问的特定资源。这包括为与客户端对象模型中的方法对应的端点指定参数。例如:Navigate from the entry point to the specific resources you want to access. This includes specifying parameters for endpoints that correspond to methods in the client object model. For example:

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

引用终结点 URI 中的 SharePoint REST 服务Reference the SharePoint REST service in your endpoint URI

使用 _api 表示终结点 URI 中的 SharePoint REST 服务。Use _api to denote the SharePoint REST service in your endpoint URIs. REST 服务是 client.svc Web 服务的一部分。The REST service is part of the client.svc web service. 但是,为了简化 REST URI 构造并缩短基本 REST URI 路径,REST 服务使用 _api 剔除显式引用 client.svc Web 服务的需求。However, to make REST URI construction easier and to shorten the base REST URI path, the REST service uses _api to abstract away the need to explicitly reference the client.svc web service.

REST 服务仍可识别和接受引用 client.svc web 服务的 URI。The REST service still recognizes and accepts URIs that reference the client.svc web service. 例如,可使用 https://{site_url}/_vti_bin/client.svc/web/lists 而不是 https://{site_url}/_api/web/listsFor example, you can use https://{site_url}/_vti_bin/client.svc/web/lists instead of https://{site_url}/_api/web/lists. 但是,首选约定是使用 _apiHowever, using _api is the preferred convention. URL 的字符数限制为 256 个,因此使用 _api 缩短基本 URI,留出更多字符用于构造 URL 的其余部分。URLs have a 256 character limit, so using _api shortens the base URI, leaving more characters for use in constructing the rest of the URL.

指定 SharePoint REST 服务的入口点Specify entry points for the SharePoint REST service

REST 服务的主入口点表示网站集和指定上下文的网站。The main entry points for the REST service represent the site collection and site of the specified context. 由此,这些入口点就对应于客户端对象模型中的 ClientContext.Site 属性和 ClientContext.Web 属性。In this way, these entry points correspond to the ClientContext.Site property and ClientContext.Web property in the client object models.

请使用以下构造访问特定的网站集合:To access a specific site collection, use the following construction:

https://{site_url}/_api/site

请使用以下构造访问特定网站:To access a specific site, use the following construction:

https://{site_url}/_api/web

除了 /site/web,REST 服务还包括几个其他访问点,这些访问点可帮助开发人员导航到特定功能。In addition to /site and /web, the REST service includes several other access points that enable developers to navigate to specific functionality. 下表列出了部分访问点。The following table lists some of these access points.

功能区Feature area 访问点Access point
网站Site https://{site_url}/_api/site
WebWeb https://{site_url}/_api/web
用户配置文件User Profile https://{site_url}/_api/SP.UserProfiles.PeopleManager
搜索Search https://{site_url}/_api/search

在这里,可以遍历对象模型,并使用客户端对象模型中的 API 名称(以正斜线 (/) 分隔),构造多个特定 REST 终结点。From here, construct more specific REST endpoints by "walking" the object model, using the names of the APIs from the client object model separated by a forward slash (/). 下表列出了客户端对象模型调用示例和同等 REST 终结点。The following table shows examples of client object model calls and the equivalent REST endpoint.

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

终结点 URI 不区分大小写。Endpoint URIs are case-insensitive. 例如在上表中,使用 /getbytitle 指定 GetByTitle() 方法的 REST 等效项。In the previous table, for example, use /getbytitle to specify the REST equivalent of the GetByTitle() method.

指定 REST 终结点 URI 中的参数Specify parameters in REST endpoint URIs

SharePoint 扩展了 OData 规范,允许您使用括号来指定方法参数和索引值。这可防止包含多个名称相同参数的 URI 中的潜在混淆问题。例如,下面两个 URI 包含名称相同的参数:SharePoint extends the OData specification to enable you to use parentheses to specify method parameters and index values. This prevents potential disambiguation issues in URIs that contain multiple parameters with the same name. For example, the following two URIs contain parameters that have the same name:

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

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

要指定多个参数,请将参数作为名称/值对包含在内,并用逗号将参数分隔。例如:To specify multiple parameters, include the parameter as a name-value pair, and separate the parameters with commas. For example:

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

下图显示了 SharePoint REST 参数语法。The following figure shows the SharePoint REST parameter syntax.

SharePoint REST 参数语法SharePoint REST parameter syntax

SharePoint REST 服务方法参数语法

复杂类型用作 REST 服务的参数Complex types as parameters for the REST service

客户端对象模型中的某些方法要求大的有效载荷作为参数。对于要与其对应客户端对象模型 API 保持功能平衡的 REST 端点,这些端点必须接受复杂类型作为参数。在这种情况下,REST 服务扩展了现有 OData 协议,允许这些 REST 端点接受单个复杂类型作为参数。这仅适用于 POST 操作,并且您必须根据 OData 标准以 Atom 格式或 JSON 格式传递复杂类型。Some methods in the client object model require a large payload as a parameter. For REST endpoints to maintain functionality parity with their corresponding client object model APIs, the endpoints must accept a complex type as a parameter. In these cases, the REST service extends the existing OData protocol to enable these REST endpoints to accept a single complex type as a parameter. This applies to POST operations only, and you have to pass the complex type in Atom format or JSON format, according to OData standards.

例如,ListCollection.Add 方法以 Microsoft.SharePoint.Client.ListCreationInformation 对象作为参数。For example, the ListCollection.Add method takes a Microsoft.SharePoint.Client.ListCreationInformation object as a parameter. 要将列表添加到指定网站,请按如下方式构造相应的 REST 终结点:To add a list to a specified site, construct the appropriate REST endpoint as follows:

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 服务调用中使用参数别名Using parameter aliases in REST service calls

您可以在 OData 中使用“参数别名”语义将参数传递到 SharePoint REST 端点。在参数别名中,用参数调用中的别名标识参数值,而实际值则在 URI 的查询字符串中指定。这允许您通过使用查询字符串支持多种类型的字符和一致的格式。You can use the "parameter aliasing" semantic in OData to pass parameters to a SharePoint REST endpoint. In parameter aliasing, the parameter value is identified with an alias in the parameter call, and the actual value is specified in the query string of the URI. This enables you to support more types of characters and consistent formatting by using the query string.

例如,以下两个 REST URI 为等效项:For example, the following two REST URIs are equivalent:

直接指定参数值:Specify the parameter value directly:

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

使用参数别名,并在 URI 的查询字符串中指定实际参数值:Use a parameter alias, and specify the actual parameter value in the query string of the URI:

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

但是,SharePoint REST 服务不支持通过参数别名传递复杂类型。例如,以下 URI(参数别名中包含复杂类型)不受支持:However, the SharePoint REST service does not support passing complex types via parameter aliasing. For example, the following URI, which contains a complex type in the parameter alias, is not supported:

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 服务参数别名语法SharePoint REST service parameter aliasing syntax

SharePoint REST 服务参数别名语法

指定字典作为参数值Specifying dictionaries as parameter values

对于与以 Dictionary<String, String> 字典作为参数的方法相对应的 REST 终结点,需在查询字符串中将字典作为一组逗号分隔的名称/值对进行传递。For REST endpoints that correspond to methods that take Dictionary<String, String> dictionaries as parameters, pass the dictionary as a series of comma delimited name-value pairs in the query string.

Dictionary 参数 REST 服务语法REST service syntax for Dictionary parameters

Dictionary 参数 REST 服务语法

Dictionary<String, object> 表示为多值对象,命名为 KeyedPropertyValue,并具有以下字符串属性:A Dictionary<String, object> is represented as a multi-value object, named KeyedPropertyValue, with the following string properties:

  • Key 多值对象的键。Key The key of the multi-value object.
  • Value 对象的值。Value The value of the object.
  • ValueType 对象的值类型。对于映射到现有实体数据模型 (EDM) 类型的简单值类型,REST 服务返回相应的 EDM 类型字符串,例如“Edm.String”。如果不是,REST 服务将返回由 Type.ToString 函数返回的值类型。ValueType The value type of the object. For simple value types that map to existing Entity Data Model (EDM) types, the REST service returns the appropriate EDM type string; for example, "Edm.String." If not, the REST service returns the value type returned by the Type.ToString function.

在查询字符串中指定参数值Specifying parameter values in the query string

如果您的 REST URI 以方法调用结束,则可以使用查询字符串语法来指定方法的参数值。例如:If your REST URI terminates in a method call, you can use query string syntax to specify the parameter values of the method. For example:

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

下图展示了查询字符串参数的 REST 服务语法。The following figure shows the REST service syntax for parameters in the query string.

查询字符串中参数的 REST 服务语法REST service syntax for parameters in query string

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

指定静态方法和属性作为 REST 服务 URISpecify static methods and properties as REST service URIs

若要构造对应于静态方法或属性的 URI,请使用 ECMAScript 对象模型中以命名空间声明开头和使用点表示法的相应 API 名称。例如,ECMAScript 客户端对象模型中的 SP.Utilities.Utility.getImageUrl(imageName) 会具有下面的 REST 等效项:To construct URIs that correspond to static methods or properties, use the corresponding API name from the ECMAScript object model, starting with the namespace declaration and using dot notation. For example, SP.Utilities.Utility.getImageUrl(imageName) in the ECMAScript client object model would have the following REST equivalent:

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

但是,静态属性只能直接访问,不允许作为较大 URI 组成的一部分。例如,允许直接访问 REST 中的 SP.Utility.AssetsLibrary 方法,如下所示:However, static properties can be accessed only directly, and are not allowed as part of a larger URI composition. For example, directly accessing the SP.Utility.AssetsLibrary method in REST is allowable, as follows:

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

但是,不允许将该资源位置用作更复杂 URI 的参数,如下例所示:However, using that resource location as a parameter for a more complex URI, as shown in the following example, is not allowed:

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

下图展示了 SharePoint REST 服务静态成员语法。The following figure shows the SharePoint REST service static member syntax.

SharePoint REST 服务静态成员语法SharePoint REST service static member syntax

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

如果要对从端点请求的数据进行选择、筛选和排序,SharePoint REST 服务支持许多不同的 OData 查询字符串运算符。If you want to select, filter, or order the data you requested from an endpoint, the SharePoint REST service supports a wide range of OData query string operators. 有关详细信息,请参阅在 SharePoint REST 请求中使用 OData 查询操作For more information, see Use OData query operations in SharePoint REST requests.

另请参阅See also