文件和文件夹 REST API 引用

最新推荐文章于 2024-09-11 09:54:20 发布

段传涛

最新推荐文章于 2024-09-11 09:54:20 发布

阅读量3k

点赞数

文件和文件夹 REST API 引用

转自：https://technet.microsoft.com/zh-cn/subscriptions/index/dn450841.aspx#bk_Overview

适用范围：apps for SharePoint | SharePoint Foundation 2013 | SharePoint Online | SharePoint Server 2013

本文内容
关于本文中的请求示例
 浏览 SharePoint 2013 文件和文件夹 REST 语法
 文件资源
 FileCollection 资源
 文件版本资源
 FileVersionCollection 资源
 Folder 资源
 FolderCollection 资源
 其他资源

关于本文中的请求示例

本文中的请求示例假设您正在使用跨域库 (SP.RequestExecutor.js) 发出跨域请求，因此它们在终结点 URI 中使用 SP.AppContextSite。有关详细信息，请参阅使用跨域库从外接程序访问 SharePoint 2013 数据。

使用请求示例之前，请执行下列操作：

更改 <应用程序 Web URL>、<主机 Web URL> 和其他占位符数据，例如 SharePoint 条目的任何 ID、名称或路径。
如果您未使用跨域库，请包括用于在所有 POST 请求中发送表单摘要值的 X-RequestDigest 标头，以及在请求正文中发送数据的 POST 请求的 content-length 标头。
如果您未发出跨域请求，请从终结点 URI 中删除SP.AppContextSite(@target)和?@target='<host web url>'。
如果您使用 OAuth，请包括 Authorization 标头 ("Authorization": "Bearer " + <access token>) 以发送 OAuth 访问令牌。
在请求示例中，从 url 和 body 属性值中删除换行符。将换行符添加到示例中，使其更易于读取。
如果您希望服务器以 Atom 格式返回响应，请删除"accept": "application/json; odata=verbose"标头。

请参阅其他资源获取有关使用跨域库、OAuth 和 SharePoint REST 服务的详细信息的链接。请参阅 REST 请求如何因环境而异和 REST 请求中使用的属性获取有关请求格式的信息。

提示
SharePoint Online REST 服务支持使用 OData$batch查询选项，将多个请求组合到对服务的单个调用中。有关详细信息和代码示例链接，请参阅使用 REST API 发出批处理请求。内部部署 SharePoint 尚不支持此选项。

浏览 SharePoint 2013 文件和文件夹 REST 语法

以可视化方式浏览SharePoint 2013 列表和列表项 REST 语法。

浏览其他 SharePoint REST 语法图表：

列表和列表项 | 用户和组

下载所有 SharePoint REST 语法图表的组合 PDF。

文件资源

表示 SharePoint 网站中的文件，该文件可以是 Web 部件页面、文档库中的项目或文件夹中的文件。

终结点 URI | 属性 | 方法 | OData 表示

终结点 URI

http://<网站 URL>/_api/web/getfilebyserverrelativeurl('/<文件夹名称>/<文件名称>')

支持的 HTTP 方法

GET | PUT (媒体资源)

GET | DELETE | POST (文件资源)

请求示例

GET 请求示例：获取文件内容（媒体资源）

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/$value
    ?@target='<host web url>'",
  method: "GET",
  binaryStringResponseBody: true,
  success: successHandler,
  error: errorHandler
});

GET 请求示例：获取文件元数据

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

PUT 请求实例：更新文件内容（媒体资源）

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.txt')/$value
    ?@target='<host web url>'",
  method: "POST",
  body: "Updated contents of the file go here",
  headers: { "X-HTTP-Method":"PUT" },
  success: successHandler,
  error: errorHandler
});

首先签出文件以避免其他用户进行更改。然后在进行了更改之后将其签回。请参阅 CheckOut 方法和 CheckIn 方法。

DELETE 请求示例：删除一个文件

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method":"DELETE" },
  success: successHandler,
  error: errorHandler
});

或者您可以使用 Recycle 方法删除文件并从已回收项中获取 GUID。

注释
请参阅 Add 方法了解介绍如何创建文件并将其添加到文件夹的示例。

文件属性

若要获取一个属性，请向属性终结点发送 GET 请求，如以下示例所示。

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

属性	类型	R/W	返回资源	描述
Author	SP.User	R	不可访问	获取一个值，该值指定添加该文件的用户。
CheckedOutByUser	SP.User	R	不可访问	获取一个值，该值返回签出文件的用户。
CheckInComment	String	R	可访问	获取一个值，该值返回在将文档签入文档库时使用的注释。
CheckOutType	Int32	R	可访问	获取一个值，该值指定如何将文件签出文档库。表示 SP.CheckOutType 值：Online = 0；Offline = 1；None = 2。文件的签出状态与文件的锁定状态无关。
ContentTag	String	R	可访问	返回内容的内部版本，用于验证文档在阅读目的方面的等同性。
CustomizedPageStatus	Int32	R	可访问	获取一个值，该值指定文件的自定义状态。表示 SP.CustomizedPageStatus 值：None = 0；Uncustomized = 1；Customized = 2。
ETag	String	R	可访问	获取指定 ETag 值的值。
Exists	Boolean	R	可访问	获取一个值，该值指定文件是否存在。
Length	Int64	R	可访问	获取以字节表示的文件的大小，不包括文件中使用的任何 Web 部件的大小。
Level	Byte	R	可访问	获取一个值，该值指定文件的发布级别。表示 SP.FileLevel 值：Published = 1；Draft = 2；Checkout = 255。
ListItemAllFields	SP.ListItem	R	不可访问	获取一个值，该值指定与此文件对应的列表项的列表项字段值。
LockedByUser	SP.User	R	不可访问	获取一个值，该值返回拥有当前文件锁的用户。
MajorVersion	Int32	R	可访问	获取一个值，该值指定文件的主要版本。
MinorVersion	Int32	R	可访问	获取一个值，该值指定文件的次要版本。
ModifiedBy	SP.User	R	不可访问	获取一个值，该值返回上次修改文件的用户。
Name	String	R	可访问	获取包括扩展名在内的文件名称。
ServerRelativeUrl	String	R	可访问	基于服务器的 URL 获取文件的相对 URL。
TimeCreated	DateTime	R	可访问	获取指定该文件的创建时间的值。
TimeLastModified	DateTime	R	可访问	获取一个值，该值指定文件的上次修改时间。
Title	String	R	可访问	获取一个值，该值指定文件的显示名称。
UiVersion	Int32	R	可访问	获取一个值，该值指定特定于实现的文件版本标识符。
UiVersionLabel	String	R	可访问	获取一个值，该值指定特定于实现的文件版本标识符。
Versions	SP.FileVersionCollection	R	不可访问	获取一个值，该值返回表示文件版本的文件版本对象的集合。

文件方法

Approve
CancelUpload
CheckIn
CheckOut
ContinueUpload
CopyTo
DeleteObject
Deny
FinishUpload
GetLimitedWebPartManager
MoveTo
OpenBinaryStream
Publish
Recycle
SaveBinaryStream
StartUpload
UndoCheckOut
Unpublish

Approve

批准已提交且需要使用指定注释进行内容审批的文件。

仅可对列表中为内容审批启用的文档进行审批。

终结点	/approve(comment)
参数	comment 类型：String 针对审批的注释。
HTTP 方法	POST
响应	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /approve(comment='Check-in comment for the approval.')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

CancelUpload 方法

停止分块上载会话，而不保存上载的数据。如果文件在库中尚不存在，将删除部分上载的文件。可使用此选项来响应用户操作（例如取消上载的请求）或错误或异常。

使用uploadId值，该值已传递到启动上载会话的 StartUpload 方法。

此方法当前仅在 Office 365 上可用。

Endpoint	/cancelupload(uploadId)
Parameters	uploadID 类型：GUID 上载会话的唯一标识符。
HTTP method	POST
Response	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /cancelupload(uploadId=guid'GUID')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

CheckIn 方法

基于签入类型将文件签入文档库。

Endpoint	/checkin(comment, checkInType)
Parameters	comment 类型：String 针对签入的注释。长度必须为 <= 1023。 checkInType 类型：Int32 文件的 SP.CheckinType：MinorCheckIn = 0；MajorCheckIn = 1；OverwriteCheckIn = 2。
HTTP method	POST
Response	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /checkin(comment='Check-in comment.',checkintype=0)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

CheckOut 方法

基于签出类型从文档库签出文件。

Endpoint	/checkout
Parameters	无
HTTP method	POST
Response	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /checkout
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

ContinueUpload 方法

使用一个附加片段继续分块上载会话。当前的文件内容不会更改。

使用uploadId值，该值已传递到启动上载会话的 StartUpload 方法。

此方法当前仅在 Office 365 上可用。

Endpoint	/continueupload(uploadId, fileOffset)
Parameters	uploadID 类型：GUID 上载会话的唯一标识符。 fileOffset 类型：Int64 片段开始的文件偏移大小。在 POST 正文中发送文件内容（数据流）。
HTTP method	POST
Response	类型：Int64 上载的总数据大小（以字节为单位）。

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /continueupload(uploadId=guid'GUID',fileOffset=8388608)
    ?@target='<host web url>'",
  method: "POST",
  body: stream containing intermediate chunk of file
  success: successHandler,
  error: errorHandler
});

CopyTo 方法

将文件复制到目标 URL。

终结点	/copyto(strNewUrl, bOverWrite)
参数	strNewUrl 类型：String 要复制到的目标文件路径的绝对 URL 或相对于服务器的 URL。 bOverWrite 类型：Boolean true 可覆盖同一位置中具有相同名称的文件；否则为 false。
HTTP method	POST
响应	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /copyto(strnewurl='/foldername/filename.docx',boverwrite=false)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

DeleteObject 方法

删除文件的建议方式是发送 DELETE 请求到 File 资源终结点，如 File 请求示例中所示。

Deny 方法

拒绝审批已提交供内容审批的文件。

仅可对列表中为内容审批启用的文档进行拒绝。

终结点	/deny(comment)
参数	comment 类型：String 针对拒绝的注释。
HTTP method	POST
响应	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /deny(comment='Check-in comment for the denial.')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

FinishUpload 方法

上载最后一个文件片段并提交该文件。此方法完成后，当前文件内容将会更改。

使用uploadId值，该值已传递到启动上载会话的 StartUpload 方法。

此方法当前仅在 Office 365 上可用。

Endpoint	/finishupload(uploadId, fileOffset)
Parameters	uploadID 类型：GUID 上载会话的唯一标识符。 fileOffset 类型：Int64 片段开始的文件偏移大小。在 POST 正文中发送文件内容（数据流）。
HTTP method	POST
Response	类型：SP.File 新上载的文件。

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /finishupload(uploadId=guid'GUID',fileOffset=125829120)
    ?@target='<host web url>'",
  method: "POST",
  body: stream containing final chunk of file
  success: successHandler,
  error: errorHandler
});

GetLimitedWebPartManager 方法

指定用于访问、修改或添加与此 Web 部件页和视图关联的 Web 部件的控件集。

如果文件不是 ASPX 页面，则引发一个异常。

终结点	/getlimitedwebpartmanager(scope)
参数	scope 类型：Int32 Web 部件页上的 SP.WebParts.PersonalizationScope 视图。User = 0; Shared = 1。
HTTP method	GET
响应	类型：SP.WebParts.LimitedWebPartManager 用于访问、修改或添加 Web 部件的关联的控件集。

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/fileName.aspx')
    /getlimitedwebpartmanager(scope=0)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

MoveTo 方法

将文件移动到指定的目标 URL。

终结点	/moveto(newUrl, flags)
参数	newUrl 类型：String 要移动到的目标文件路径的绝对 URL 或相对于服务器的 URL。 flags 类型：Int32 如何移动文件的按位 SP.MoveOperations 值。Overwrite = 1; AllowBrokenThickets（即使支持文件与文件分离，也会移动）= 8。
HTTP method	POST
响应	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /moveto(newurl='/Other Folder/filename.docx',flags=1)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OpenBinaryStream 方法

打开作为数据流的文件。

终结点	/openbinarystream
参数	无
HTTP method	GET
响应	类型：Stream 指定的文件数据流。

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /openbinarystream
    ?@target='<host web url>'",
  method: "GET",
  binaryStringResponseBody: true,
  success: successHandler,
  error: errorHandler
});

注释
或者您可以使用文件资源中的 $value 打开文件。示例：…/getfilebyserverrelativeurl('/Shared Documents/filename.docx')/$value。

Publish 方法

提交文件以使用指定的注释进行内容审批。

终结点	/publish(comment)
参数	comment 类型：String 针对已发布文件的注释。长度必须为 <= 1023。
HTTP method	POST
响应	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /publish(comment='Check-in comment for the publish operation.')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

Recycle 方法

将文件移到回收站并返回新回收站项目的标识符。

终结点	/recycle
参数	无
HTTP method	POST
响应	类型：GUID 已回收文件的 GUID。

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /recycle
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

SaveBinaryStream 方法

终结点	/savebinary
参数	在 POST 正文中发送文件内容（数据流）。
HTTP method	POST
响应	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /savebinarystream
    ?@target='<host web url>'",
  method: "POST",
  body: "This is the new content.",
  success: successHandler,
  error: errorHandler
});

StartUpload 方法

启动一个新的块上载会话并上载第一个片段。此方法完成时不更改当前文件内容。只要对 uploadId 和 stream 使用相同值，方法就为幂等（因此不会更改结果）。当您使用 CancelUpload 方法时，或者当您通过 ContinueUpload 和 FinishUpload 方法传递其余文件内容成功完成上载会话时，上载会话结束。

例如，您可以将一个 35 MB 的文件分成三个 10 MB 流和一个 5 MB 流并将它们上载（使用生成的偏移值 10、20 和 30 MB）来传递该文件：

startUpload(GUID, stream1)
continueUpload(GUID, 10 MB, stream2)
continueUpload(GUID, 20 MB, stream3)
finishUpload(GUID, 30 MB, stream4)

StartUpload 和 ContinueUpload 方法返回上载的总数据大小（以字节为单位），因此您可以传递这些返回值供 ContinueUpload 和 FinishUpload 后续使用。

此方法当前仅在 Office 365 上可用。

Endpoint	/startupload(uploadId)
Parameters	uploadID 类型：GUID 上载会话的唯一标识符。在 POST 正文中发送文件内容（数据流）。
HTTP method	POST
Response	类型：Int64 上载的数据大小（以字节为单位）。

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /startupload(uploadId=guid'GUID')
    ?@target='<host web url>'",
  method: "POST",
  body: stream containing first chunk of file
  success: successHandler,
  error: errorHandler
});

UndoCheckOut 方法

恢复文件的现有签出行为。

终结点	/undocheckout
参数	无
HTTP method	POST
响应	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /undocheckout
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

Unpublish 方法

从内容审批中删除文件或取消发布主要版本。

终结点	/unpublish
参数	comment 类型：String 针对取消发布操作的注释。长度必须为 <= 1023。
HTTP method	POST
响应	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /unpublish(comment='Check-in comment for the unpublish operation.')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OData 表示

以下示例表示 JSON 格式的 File 资源。

{"d":{
  "__metadata":{,
    "id":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared Documents/folderName/fileName.docx')",
    "uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName.docx')",
    "type":"SP.File"
  },
  "Author":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName.docx')/Author"}},
  "CheckedOutByUser":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName.docx')/CheckedOutByUser"}},
  "ListItemAllFields":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName.docx')/ListItemAllFields"}},
  "LockedByUser":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName.docx')/LockedByUser"}},
  "ModifiedBy":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName.docx')/ModifiedBy"}},
  "Versions":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName.docx')/Versions"}},
  "CheckInComment":"Revisions to the file.",
  "CheckOutType":2,
  "ContentTag":"{2FBB0C3C-4059-41A2-A5CF-3E076EA0A94C},2,3",
  "CustomizedPageStatus":0,
  "ETag":"\"{2FBB0C3C-4059-41A2-A5CF-3E076EA0A94C},2\"",
  "Exists":true,
  "Length":"20609",
  "Level":1,
  "MajorVersion":1,
  "MinorVersion":0,
  "Name":"fileName.docx",
  "ServerRelativeUrl":"/Shared Documents/folderName/fileName.docx",
  "TimeCreated":"2013-05-16T21:01:23Z",
  "TimeLastModified":"2013-05-18T04:57:32Z",
  "Title":"",
  "UIVersion":512,
  "UIVersionLabel":"1.0"
}}

FileCollection 资源

表示 File 资源的集合。

终结点 URI | 方法 | OData 表示

终结点 URI

http://<网站 URL>/_api/web/getfolderbyserverrelativeurl('/<文件夹名称>')/files

支持的 HTTP 方法

GET | POST

请求示例

GET 请求示例：获取文件夹中所有文件的元数据

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')/files
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET 请求示例：通过文件名称获取文件内容（媒体资源）

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')/files('filename.docx')/$value
    ?@target='<host web url>'",
  method: "GET",
  binaryStringResponseBody: true,
  success: successHandler,
  error: errorHandler
});

GET 请求示例：获取文件元数据

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')/files('filename.docx')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
};

请参阅 File 请求示例以获取如何使用 GetFileByServerRelativeUrl 终结点检索文件以及如何更新和删除文件的示例。若要创建文件，请参阅 Add 方法。

FileCollection 方法

Add
AddTemplateFile
GetByUrl

Add 方法

终结点	/add(content, overwrite, url)
参数	content 类型：Stream 文件的内容。在请求正文中传递 content 参数。可以使用 REST API 添加的二进制文件最大大小为 2 GB。 overwrite 类型：Boolean true 可覆盖文件（如果文件已存在）；否则为 false。 url 类型：String 文件的相对于文件夹的 URL。
HTTP method	POST
响应	类型：SP.File 新文件。

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')/files
    /add(overwrite=true,url='filename.txt')
    ?@target='<host web url>'",
  method: "POST",
  body: "Contents of the file go here",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

以下示例显示如何使用跨域库上载二进制文件，这需要将文件流转换为字符串。有关 jQuery 示例，请参阅使用 REST API 和 jQuery 上载文件。

JavaScript

function addFile(arrayBuffer) { 
    var executor = new SP.RequestExecutor(appWebUrl);

    // Construct the endpoint.
    // The GetList method is available for SharePoint Online only. 
    var fileCollectionEndpoint = String.format(
         "{0}/_api/sp.appcontextsite(@target)/web/getlist('{1}')/" +
         "rootfolder/files/add(overwrite=true, url='{2}')?@target='{3}'",
         appWebUrl, listName, fileName, hostWebUrl);

    var fileData = '';
    var byteArray = new Uint8Array(arrayBuffer);
    for (var i = 0; i < byteArray.byteLength; i++) {
        fileData += String.fromCharCode(byteArray[i]);
    }

    // Send the request.
    executor.executeAsync({
        url: fileCollectionEndpoint,
        method: "POST",
        body: fileData,
        binaryStringRequestBody: true,
        headers: {"accept":"application/json;odata=verbose"},
        success: function (data) {
            alert('File upload succeeded.');
        },
        error: function (err) {
            alert('Error: ' + err.responseText);
        }
    });
}

AddTemplateFile 方法

向现有列表或文档库中添加幻影文件。

终结点	/addTemplateFile(urlOfFile,templateFileType)
参数	urlOfFile 类型：String 您希望保存文件的相对于服务器的 URL。 templateFileType 类型：Int32 用于创建文件的 SP.TemplateFileType：StandardPage = 0; WikiPage = 1; FormPage = 2。
HTTP method	POST
响应	类型：SP.File 已添加的模板文件。

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents')/files
    /addtemplatefile(urloffile='/Shared Documents/newwikipage.aspx',templatefiletype=1)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetByUrl 方法

获取指定 URL 处的文件。

获取文件的建议方式是通过 GetFileByServerRelativeUrl 终结点。请参阅 SP.File 请求示例。

终结点	/getbyurl('<文件名称或相对于服务器的 URL>')
参数	无
HTTP method	GET
响应	类型：SP.File 指定 URL 的文件。

请求示例

获取文件内容（媒体资源）

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/foldername')/files
    /getbyurl('filename.docx')/$value
    ?@target='<host web url>'",
  method: "GET",
  binaryStringResponseBody: true,
  success: successHandler,
  error: errorHandler
});

获取文件的元数据（文件资源）

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/foldername')/files
    /getbyurl('filename.docx')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

请参阅File 请求示例和FileCollection 请求示例以查看获取文件的其他方式。

OData 表示

以下示例表示 JSON 格式的文件集合资源。

{"d":{
  "results":[{
    "__metadata":{
      "id":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared Documents/folderName/fileName1.docx')",
      "uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName1.docx')",
      "type":"SP.File"
    },
    "Author":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName1.docx')/Author"}},
    "CheckedOutByUser":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName1.docx')/CheckedOutByUser"}},
    "ListItemAllFields":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName1.docx')/ListItemAllFields"}},
    "LockedByUser":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName1.docx')/LockedByUser"}},
    "ModifiedBy":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName1.docx')/ModifiedBy"}},
    "Versions":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName1.docx')/Versions"}},
    "CheckInComment":"",
    "CheckOutType":2,
    "ContentTag":"{2FBB0C3C-4059-41A2-A5CF-3E076EA0A94C},4,7",
    "CustomizedPageStatus":0,
    "ETag":"\"{2FBB0C3C-4059-41A2-A5CF-3E076EA0A94C},4\"",
    "Exists":true,
    "Length":"20609",
    "Level":1,
    "MajorVersion":1,
    "MinorVersion":0,
    "Name":"fileName1.docx",
    "ServerRelativeUrl":"/Shared Documents/folderName/fileName1.docx",
    "TimeCreated":"2013-05-16T21:01:23Z",
    "TimeLastModified":"2013-06-09T02:38:14Z",
    "Title":"Title of fileName1",
    "UIVersion":512,
    "UIVersionLabel":"1.0"
    },{
    "__metadata":{
      "id":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared Documents/folderName/fileName2.docx')",
      "uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName2.docx')",
      "type":"SP.File"
    },
    "Author":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName2.docx')/Author"}},
    "CheckedOutByUser":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName2.docx')/CheckedOutByUser"}},
    "ListItemAllFields":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName2.docx')/ListItemAllFields"}},
    "LockedByUser":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName2.docx')/LockedByUser"}},
    "ModifiedBy":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName2.docx')/ModifiedBy"}},
    "Versions":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName2.docx')/Versions"}},
    "CheckInComment":"",
    "CheckOutType":2,
    "ContentTag":"{E654B970-C4BF-4DC5-9719-B5B01CAD6FD9},4,9",
    "CustomizedPageStatus":0,
    "ETag":"\"{E654B970-C4BF-4DC5-9719-B5B01CAD6FD9},4\"",
    "Exists":true,
    "Length":"12263",
    "Level":1,
    "MajorVersion":1,
    "MinorVersion":0,
    "Name":"fileName2.docx",
    "ServerRelativeUrl":"/Shared Documents/folderName/fileName2.docx",
    "TimeCreated":"2013-05-18T05:01:51Z",
    "TimeLastModified":"2013-06-09T02:38:59Z",
    "Title":"Title of fileName2",
    "UIVersion":512,
    "UIVersionLabel":"1.0"
  }]}}

文件版本资源

表示 File 资源的版本。

终结点 URI | 属性 | 方法 | OData 表示

终结点 URI

http://<网站 URL>/_api/web/getfilebyserverrelativeurl('/<文件夹名称>/<文件名称>')/versions(<版本 ID>)

支持的 HTTP 方法

GET | POST | DELETE

请求示例

GET 请求示例：获取文件版本的元数据

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions(512)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

DELETE 请求示例：删除文件的特定版本

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions(513)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method":"DELETE" },
  success: successHandler,
  error: errorHandler
});

FileVersion 属性

若要获取一个属性，请向属性终结点发送 GET 请求，如以下示例所示。

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /versions(512)/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

属性	类型	R/W	返回资源	描述
CheckInComment	String	R	可访问	获取一个值，该值指定签入注释。
Created	DateTime	R	可访问	获取一个值，该值指定文件版本的创建日期和时间。
CreatedBy	SP.User	R	不可访问	获取一个值，该值指定表示文件版本的创建者的用户。
ID	Int32	R	可访问	获取文件版本的内部标识符。
IsCurrentVersion	Boolean	R	可访问	获取一个值，该值指定文件版本是否是当前版本。
Size	Int32	R	可访问
Url	String	R	可访问	获取一个值，该值指定文件版本的相对 URL，以网站或子网站的 URL 为基础。
VersionLabel	String	R	可访问	获取一个值，该值指定特定于实现的文件标识符。使用 majorVersionNumber.minorVersionNumber 格式，例如：1.2。

FileVersion 方法

DeleteObject

DeleteObject 方法

删除文件版本的建议方式是发送 DELETE 请求到 FileVersion 资源终结点，如 FileVersion 请求示例中所示。

OData 表示

以下示例表示 JSON 格式的 FileVersion 资源。

{"d":{
  "__metadata":{,
    "id":"http://<site url>/_api/web/getfilebyserverrelativeurl('/Shared Documents/folderName/fileName1.docx')/versions(512)",
    "uri":"http://<site url>/_api/web/getfilebyserverrelativeurl('/Shared%20Documents/folderName/fileName1.docx')/versions(512)",
    "type":"SP.FileVersion"
  },
  "CreatedBy":{"__deferred":{"uri":"http://<site url>/_api/web/getfilebyserverrelativeurl('/Shared%20Documents/folderName/fileName1.docx')/versions(512)/CreatedBy"}},
  "CheckInComment":"Revisions to the file.",
  "Created":"2013-06-10T04:02:53Z",
  "ID":512,
  "IsCurrentVersion":true,
  "Size":20609,
  "Url":"_vti_history/512/Shared Documents/folderName/fileName1.docx",
  "VersionLabel":"1.0"
}}

FileVersionCollection 资源

表示 FileVersion 资源的集合。

终结点 URI | 方法 | OData 表示

终结点 URI

http://<网站 URL>/_api/web/getfilebyserverrelativeurl('/<文件夹名称>/<文件名称>')/versions

HTTP 方法

此资源支持以下 HTTP 方法：

GET | POST

请求示例

GET 请求示例：获取文件所有版本的元数据

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET 请求示例：获取文件版本的元数据

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions(512)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

FileVersionCollection 方法

DeleteAll
DeleteById
DeleteByLabel
GetById
RestoreByLabel

DeleteAll 方法

删除集合中的所有文件版本对象。

终结点	/deleteall
参数	无
HTTP method	POST
响应	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions
    /deleteall
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

DeleteById 方法

删除文件的指定版本。

终结点	/deletebyid(vid)
参数	vid 类型：Int32 要删除的文件版本 ID。
HTTP method	POST
响应	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions
    /deletebyid(vid=3)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

DeleteByLabel 方法

删除具有指定版本标签的文件版本对象。

终结点	/deletebylabel(versionlabel)
参数	versionlabel 类型：String 要删除的文件版本的 SP.FileVersion.VersionLabel 属性。
HTTP method	POST
响应	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions
    /deletebylabel(versionlabel='1.2')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

GetById 方法

终结点	/getbyid(versionid)
参数	versionid 类型：Int32 要获取的文件版本 ID。
HTTP method	GET
响应	类型：SP.FileVersion 指定的文件版本。

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions
    /getbyid(512)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

或者您可以直接将版本 ID 传递到集合 (…/versions(512))。请参阅FileVersionCollection 请求示例。

RestoreByLabel 方法

从版本标签指定的文件创建新文件版本。

终结点	/restorebylabel(versionlabel)
参数	versionlabel 类型：String 要恢复的文件版本的 SP.FileVersion.VersionLabel 属性。
HTTP method	POST
响应	无

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions
    /restorebylabel(versionlabel='1.2')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OData 表示

以下示例表示 JSON 格式的 FileVersionCollection 资源。

{"d":{
  "results":[{
    "__metadata":{
      "id":"http://<site url>/_api/SP.FileVersiona6a6bb00-2b96-41e6-a901-46df015183b9",
      "uri":"http://<site url>/_api/SP.FileVersiona6a6bb00-2b96-41e6-a901-46df015183b9",
      "type":"SP.FileVersion"
    },
    "CreatedBy":{"__deferred":{"uri":"http://<site url>/_api/SP.FileVersiona6a6bb00-2b96-41e6-a901-46df015183b9/CreatedBy"}},
    "CheckInComment":"",
    "Created":"2013-06-10T04:02:53Z",
    "ID":512,
    "IsCurrentVersion":true,
    "Size":20609,
    "Url":"_vti_history/512/Shared Documents/folderName/fileName1.docx",
    "VersionLabel":"1.0"
    },{
    "__metadata":{
      "id":"http://<site url>/_api/SP.FileVersion6accd876-7579-47b6-9779-19a24f6ab8a1",
      "uri":"http://<site url>/_api/SP.FileVersion6accd876-7579-47b6-9779-19a24f6ab8a1",
      "type":"SP.FileVersion"
    },
    "CreatedBy":{"__deferred":{"uri":"http://<site url>/_api/SP.FileVersion6accd876-7579-47b6-9779-19a24f6ab8a1/CreatedBy"}},
    "CheckInComment":"Revisions to the file.",
    "Created":"2013-06-11T17:42:41Z",
    "ID":513,
    "IsCurrentVersion":false,
    "Size":17973,
    "Url":"_vti_history/513/Shared Documents/folderName/fileName1.docx",
    "VersionLabel":"1.1"
  }]}}

Folder 资源

表示 SharePoint 网站上的文件夹。

终结点 URI | 属性 | 方法 | OData 表示

终结点 URI

http://<网站 URL>/_api/web/getfolderbyserverrelativeurl('/<文件夹名称>')

支持的 HTTP 方法

GET | POST | DELETE | MERGE | PUT

请求示例

GET 请求示例：获取一个文件夹

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

MERGE 请求示例：更改一个文件夹

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.Folder' }, 'WelcomePage':'Folder B/WelcomePage.aspx' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

DELETE 请求示例：删除一个文件夹

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method":"DELETE" },
  success: successHandler,
  error: errorHandler
});

请参阅 FolderCollection 请求示例以获取如何创建文件夹的示例。

Folder 属性

若要获取一个属性，请向属性终结点发送 GET 请求，如以下示例所示。

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

若要设置一个可写属性、获取资源、在正文中设置属性值，然后使用资源上的 MERGE 方法合并更改，或使用 PUT 方法替换资源。请参阅 Folder 请求示例以获取示例。

属性	类型	R/W	返回资源	描述
ContentTypeOrder	Collection(SP.ContentTypeId)	R	可访问	指定内容类型的显示顺序。
Files	SP.FileCollection	R	不可访问	获取列表文件夹中包含的所有文件的集合。您可以使用文件夹的 FileCollection 资源中的 Add 方法将一个文件添加到文件夹。
Folders	SP.FolderCollection	R	不可访问	获取列表文件夹中包含的列表文件夹的集合。
ItemCount	Int32	R	可访问	获取一个值，该值指定列表文件夹中的项计数。
ListItemAllFields	SP.ListItem	R	不可访问	指定与此文件对应的列表项的列表项字段 (2) 值。
Name	String	R	可访问	获取文件夹的名称。
ParentFolder	SP.Folder	R	不可访问	获取该文件夹的父列表文件夹。
Properties	SP.PropertyValues	R	不可访问	获取文件夹中包含的所有文件的集合。
ServerRelativeUrl	String	R	可访问	获取列表文件夹相对于服务器的 URL。
UniqueContentTypeOrder	Collection(SP.ContentTypeId)	RW	可访问	获取或设置一个值，该值指定内容类型顺序。
WelcomePage	String	RW	可访问	获取或设置一个值，该值指定列表文件夹欢迎页面相对于文件夹的 URL。

Folder 方法

DeleteObject
Recycle

DeleteObject 方法

删除文件夹的建议方式是发送 DELETE 请求到 Folder 资源终结点，如 Folder 请求示例中所示。

Recycle 方法

将列表文件夹移到回收站并返回新回收站项目的标识符。

终结点	/recycle
HTTP method	POST
参数	无
响应	类型：GUID 回收操作的 ID。

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')
    /recycle
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

OData 表示

以下示例表示 JSON 格式的 Folder 资源。

{"d":{
  "__metadata":{,
    "id":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared Documents/Folder A')",
    "uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Folder%20A')",
    "type":"SP.Folder"
  },
  "Files":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Folder%20A')/Files"}},
  "ListItemAllFields":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Folder%20A')/ListItemAllFields"}},
  "ParentFolder":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Folder%20A')/ParentFolder"}},
  "Properties":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Folder%20A')/Properties"}},
  "Folders":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Folder%20A')/Folders"}},
  "ItemCount":7,
  "Name":"Folder A",
  "ServerRelativeUrl":"/Shared Documents/Folder A",
  "WelcomePage":""
}}

FolderCollection 资源

表示 Folder 资源的集合。

终结点 URI | 方法 | OData 表示

终结点 URI

http://<网站 URL>/_api/web/folders (根网站的顶级文件夹)
http://<网站 URL>/_api/web/getfolderbyserverrelativeurl('/<文件夹名称>')/folders

支持的 HTTP 方法

GET | POST

请求示例

GET 请求示例：获取根网站的文件夹

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/folders
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET 请求示例：获取文档库中的文件夹

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents')/folders
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET 请求示例：通过名称获取文件夹

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')/folders('Folder B')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST 请求示例：创建一个文件夹（或者您可以使用 Add 方法）

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')/folders
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.Folder' }, 'ServerRelativeUrl':'Folder B' }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

请参阅Folder 请求示例以获取如何更新和删除文件夹的示例。

FolderCollection 方法

Add
GetByUrl

Add 方法

向集合中添加位于指定 URL 处的文件夹。

终结点	/add(url)
参数	url 类型：String 您希望添加文件夹（包括新文件夹的名称）的路径，如完全限定的 URL、相对于服务器的 URL 或相对于网站的 URL。
HTTP method	POST
响应	类型：SP.Folder 新添加的文件夹。

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/folders
    /add('/Shared Documents/Folder A/Folder B')
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetByUrl 方法

终结点	/getbyurl('<相对于服务器的文件夹 URL>')
参数	类型：String 文件夹的相对于服务器的 URL。
HTTP method	GET
响应	类型：SP.Folder 指定的文件夹。

请求示例

JavaScript

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/folders
    /getbyurl('Folder B')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

您还可以直接将文件夹名称传递到文件夹集合。示例：…/folders('Folder B')。请参阅 FolderCollection 请求示例。

OData 表示

以下示例表示 JSON 格式的 FolderCollection 资源。

{"d":{
  "results":[{
    "__metadata":{
      "id":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared Documents/Forms')",
      "uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Forms')",
      "type":"SP.Folder"
    },
    "Files":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Forms')/Files"}},
    "ListItemAllFields":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Forms')/ListItemAllFields"}},
    "ParentFolder":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Forms')/ParentFolder"}},
    "Properties":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Forms')/Properties"}},
    "Folders":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Forms')/Folders"}},
    "ItemCount":0,
    "Name":"Forms",
    "ServerRelativeUrl":"/Shared Documents/Forms",
    "WelcomePage":""
    },{
    "__metadata":{
      "id":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared Documents/folderName')",
      "uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/folderName')",
      "type":"SP.Folder"
    },
    "Files":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/folderName')/Files"}},
    "ListItemAllFields":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/folderName')/ListItemAllFields"}},
    "ParentFolder":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/folderName')/ParentFolder"}},
    "Properties":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/folderName')/Properties"}},
    "Folders":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/folderName')/Folders"}},
    "ItemCount":4,
    "Name":"folderName",
    "ServerRelativeUrl":"/Shared Documents/folderName",
    "WelcomePage":""
  }]}}