导航 REST 服务中表示的 SharePoint 数据结构Navigate the SharePoint data structure represented in the REST service

使用 SharePoint REST 服务时,通常首先知道某个特定的 SharePoint 项的 URL,但需要访问相关项,例如该项所在的文件夹或库结构。When you're working with the SharePoint REST service, you'll often start out knowing the URL of a specific SharePoint item, but want to access related items, such as the folder or library structure where that item resides. 例如,假设创建外接程序,用户在其中输入 SharePoint 库中文档的 URL。For example, suppose you create an add-in where your user enters the URL of a document in a SharePoint library. 加载项必须分解该 URL 以获取实际的 SharePoint 网站 URL。Your add-in must then break down that URL to figure out the actual SharePoint site URL. 完成该操作后,加载项将代表用户从此网站进行更多请求,如创建、更新或删除相关项或资源。After it's done that, the add-in can then make more requests from the site on the user's behalf, such as to create, update, or delete related items or resources.

为此,加载项需要查询 SharePoint,以获取以下信息:To do this, your add-in needs to query SharePoint for the following information:

  • 包含该资源的网站和网站集的服务器相对 URL。The server relative URLs of the site and site collection containing the resource.
  • 可执行更改资源状态请求的表单摘要,如 POSTPUTMERGEDELETEA form digest to enable you to perform requests that change the state of the resource, such as POST, PUT, MERGE, and DELETE.

基本流程The basic process

  1. /contextinfo 运算符与给定的 URL 配合使用,以访问网站和网站集地址和表单摘要。Use the /contextinfo operator with the given URL to access the site and site collection addresses, and the form digest. 使用如下格式的 /contextinfo 运算符:Use the /contextinfo operator in the following format:

    POST https://{site_url}/_api/contextinfo
    Authorization: "Bearer " + accessToken
    Accept: "application/json;odata=verbose"
    

    为了提高安全性,防止跨站点脚本尝试,/contextinfo 运算符仅接受 POST 请求。To increase security against cross-site scripting attempts, the /contextinfo operator accepts only POST requests.

  2. 使用 /contextinfo 运算符返回的 SPContextWebInformation 对象属性根据需要访问其他资源。Use the SPContextWebInformation object properties that the /contextinfo operator returns to access additional resources as desired.

试用Try it

  1. 从给定的 SharePoint 项的 URL 开始。例如:https://{site_url}/doclib/myDocument.docxStart with a URL to a given SharePoint item. For example: https://{site_url}/doclib/myDocument.docx

  2. 从 URL 的结尾处删除指定资源的名称,以便 URL 指向文档库、文件夹或列表。Remove the name of the specific resource from the end of the URL, so that the URL points to a document library, folder, or list. 在本示例中为:https://{site_url}/doclib/In this case: https://{site_url}/doclib/

  3. 向 URL 追加 REST 服务指针和 /contextinfo 运算符:Append the REST service pointer and the /contextinfo operator to the URL:

    POST https://{site_url}/_api/doclib/contextinfo
    Authorization: "Bearer " + accessToken
    Accept: "application/json;odata=verbose"
    
  4. 读取响应中的表单摘要和 webFullUrl 属性。Read the form digest and webFullUrl properties from the response.

  5. 向 Web URL 追加 REST 服务指针 _apiAppend the REST service pointer _api to the web URL.

  6. 使用生成的 URL 和表单摘要请求其他所需资源。Use the resulting URL and the form digest to make requests for other resources you need.

提示

如果要进行 GET 请求,或者使用经验证的 OAuth 令牌提出请求,无需传递表单摘要。You don't have to pass the form digest if you're making GET requests, or making requests using a validated OAuth token.

如果使用 SharePoint 服务器对象模型导航站点结构,可以使用 SPWeb.ParentWebSPWeb.Webs 属性访问表示父站点和子站点的对象。When you navigate your site structure using the SharePoint server object model, you use the SPWeb.ParentWeb and SPWeb.Webs properties to access objects that represent parent and child sites.

对应的 REST 资源(web/parentwebweb/webs)不返回表示站点的对象。The corresponding REST resources, web/parentweb and web/webs, don't return objects that represent sites. 这是因为 REST 服务符合 OData 标准,而返回完整的站点表示形式会导致此类请求效率低下。This is because the REST service conforms to OData standards, and returning complete site representations would make such requests inefficient. 相反,它们返回包含站点标量属性的 WebInfo 对象,但其中不包含集合或字段集合等相关实体集。Instead, they return a WebInfo object that contains the site's scalar properties, but without related entity sets such as like collections or field collections.

若要转到特定父站点或子站点,请使用 IdTitle 属性构造相应站点的 REST URL。To navigate to a specific parent or child site, construct the appropriate REST URL to that site by using the Id or Title property. 由此,可访问相应站点的相关实体集。From there, you can access that site's related entity sets.

SharePoint REST 服务不支持通过 URL 构造遍历网站的文件夹层次结构。The SharePoint REST service does not support traversing the folder hierarchy of a site through the URL construction. 请改用与 Web.GetFolderByServerRelativeUrl 方法等效的 REST。Instead, use the REST equivalent of the Web.GetFolderByServerRelativeUrl method. 例如:For example:

REST 服务不支持的导航:Navigation not supported through the REST service:

https://{site_url}/_vti_bin/client.svc/web/lists/SharedDocuments/folder1/stuff/things/Recycle

REST 服务支持的导航:Navigation that is supported by the REST service:

https://{site_url}/_vti_bin/client.svc/web/GetFolderByServerRelativeUrl('SharedDocuments/folder1/stuff/things')/Recycle

SPContextWebInformation 对象属性SPContextWebInformation object properties

SPContextWebInformation 属性SPContextWebInformation Property 说明Description
webFullUrlwebFullUrl 获取最近网站相对于服务器的 URL。Gets the server-relative URL of the nearest site.
siteFullUrlsiteFullUrl 获取包含网站的网站集根的服务器相关 URL。Gets the server-relative URL of the root of the site collection that the site is contained within.
如果最近的 Web 是某网站集的根,那么 webFullUrl 属性的值等于 siteFullUrl 属性的值。If the nearest web is the root of a site collection, the value of the webFullUrl property is equal to the siteFullUrl property.
formDigestValueformDigestValue 获取服务器的请求表单摘要。Gets the server's request form digest.
LibraryVersionLibraryVersion 获取当前版本的 REST 库。Gets the current version of the REST library.
SupportedSchemaVersionsSupportedSchemaVersions 获取支持的 REST/CSOM 库的架构版本。Gets the versions of the schema of the REST/CSOM library that are supported.

WebInfo 对象WebInfo object

WebInfo 属性WebInfo property 说明Description
创建时间Created 获取一个值,该值指定网站的创建时间。Gets a value that specifies when the site was created.
说明Description 获取或设置网站的说明。Gets or sets the description for the site.
IDId 获取一个值,该值指定网站标识符。Gets a value that specifies the site identifier.
语言Language 获取一个值,该值指定网站上所使用的语言的区域设置 ID (LCID)。Gets a value that specifies the locale ID (LCID) for the language that is used on the site.
LastItemModifiedDateLastItemModifiedDate 获取一个值,该值指定某个项在网站中最后一次修改的时间。Gets a value that specifies when an item was last modified on the site.
标题Title 获取或设置网站的标题。Gets or sets the title for the site.
WebTemplateIdWebTemplateId 获取网站模板的标识符。Gets the identifier of the site template.

另请参阅See also