使用 REST 处理文件夹和文件
注意
此页上的示例不支持 % 和 # 字符。 通过 ResourcePath API 支持文件和文件夹中的 % 和 #
提示
SharePoint Online（和本地 SharePoint 2016 及更高版本）REST 服务支持使用 OData $batch 查询选项，将多个请求合并到一个服务调用中。 有关详细信息和代码示例链接，请参阅使用 REST API 发出批处理请求。
使用 REST 处理文件夹
如果知道文件夹 URL，可以在文档库内检索文件夹。 例如，可使用下面示例中的终结点，检索共享文档库的根文件夹。
GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Shared Documents')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
下面的 XML 示例展示了在请求获取 XML 内容类型时返回的文件夹属性。
<content type="application/xml">
<m:properties>
<d:ItemCount m:type="Edm.Int32">0</d:ItemCount>
<d:Name>Shared Documents</d:Name>
<d:ServerRelativeUrl>/Shared Documents</d:ServerRelativeUrl>
<d:WelcomePage/>
</m:properties>
</content>
下面的示例展示了如何创建文件夹。
POST https://{site_url}/_api/web/folders
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"
{
"__metadata": {
"type": "SP.Folder"
},
"ServerRelativeUrl": "/document library relative url/folder name"
}
下面的示例展示了如何使用 MERGE 方法重命名文件夹。
首先，通过 GET 请求获取文件夹的 OData 类型。
GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/ListItemAllFields
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
在结果中，获取 odata.type 值，如 SP.Data.Shared_x0020_DocumentsItem（值可能因库配置而异）。 然后提交 MERGE 请求：
POST https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/ListItemAllFields
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
If-Match: "{etag or *}"
X-HTTP-Method: "MERGE"
X-RequestDigest: "{form_digest_value}"
{
"__metadata": {
"type": "{odata.type from previous call}"
},
"Title": "New name",
"FileLeafRef": "New name"
}
下面的示例展示了如何删除文件夹。
POST https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')
Authorization: "Bearer " + accessToken
If-Match: "{etag or *}"
X-HTTP-Method: "DELETE"
X-RequestDigest: "{form_digest_value}"
使用 REST 处理文件
下面的示例展示了如何检索文件夹中的所有文件。
GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files
method: GET
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
下面的示例展示了如何检索特定文件。
GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files('{file_name}')/$value
Authorization: "Bearer " + accessToken
如下面的示例所示，如果知道文件 URL，还可以检索文件。
GET https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')/$value
Authorization: "Bearer " + accessToken
下面的代码示例演示了在你知道文件的 URL 时， 如何通过使用上述 REST 终结点和 C# 来检索文件。
/// <summary>
/// Download File Via Rest API
/// </summary>
/// <param name="webUrl">https://xxxxx/sites/DevSite</param>
/// <param name="credentials"></param>
/// <param name="documentLibName">MyDocumentLibrary</param>
/// <param name="fileName">test.docx</param>
/// <param name="path">C:\\</param>
public static void DownloadFileViaRestAPI(string webUrl, ICredentials credentials, string documentLibName, string fileName, string path)
{
webUrl = webUrl.EndsWith("/") ? webUrl.Substring(0, webUrl.Length - 1) : webUrl;
string webRelativeUrl = null;
if (webUrl.Split('/').Length > 3)
{
webRelativeUrl = "/" + webUrl.Split(new char[] { '/' }, 4)[3];
}
else
{
webRelativeUrl = "";
}
using (WebClient client = new WebClient())
{
client.Headers.Add("X-FORMS_BASED_AUTH_ACCEPTED", "f");
client.Credentials = credentials;
Uri endpointUri = new Uri(webUrl + "/_api/web/GetFileByServerRelativeUrl('" + webRelativeUrl + "/" + documentLibName + "/" + fileName + "')/$value");
byte[] data = client.DownloadData(endpointUri);
FileStream outputStream = new FileStream(path + fileName, FileMode.OpenOrCreate | FileMode.Append, FileAccess.Write, FileShare.None);
outputStream.Write(data, 0, data.Length);
outputStream.Flush(true);
outputStream.Close();
}
}
static void Main(string[] args)
{
string siteURL = "https://xxxxx/sites/DevSite";
//set credential of SharePoint online
SecureString secureString = new SecureString();
foreach (char c in "Password".ToCharArray())
{
secureString.AppendChar(c);
}
ICredentials credentials = new SharePointOnlineCredentials("xxxxxx.onmicrosoft.com", secureString);
//set credential of SharePoint 2013(On-Premises)
//string userName = "Administrator";
//string password = "xxxxxxx";
//string domain = "CONTOSO";
//ICredentials credentials = new NetworkCredential(userName, password, domain);
DownloadFileViaRestAPI(siteURL, credentials, "MyDocumentLib", "test.docx", "c:\\");
Console.WriteLine("success");
Console.ReadLine();
}
下面的示例展示了如何创建文件并将它添加到文件夹中。
POST https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files/add(url='a.txt',overwrite=true)
Authorization: "Bearer " + accessToken
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"
"Contents of file"
下面的示例展示了如何使用 PUT 方法更新文件。
注意
PUT 是可用于更新文件的唯一方法。 不允许使用 MERGE 方法。
POST https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')/$value
Authorization: "Bearer " + accessToken
Content-Length: {length of request body as integer}
X-HTTP-Method: "PUT"
X-RequestDigest: "{form_digest_value}"
"Contents of file"
必须构造到达列表项形式的文件的终结点，才能更新文件元数据。 由于每个文件夹是一个列表且每个文件是一个列表项，所以可以执行此操作。 构造一个终结点，如下所示：https://{site_url}/_api/web/lists/getbytitle('Documents')/items({item_id})。 有关如何更新列表项元数据的信息，请参阅使用 REST 处理列表和列表项。
更新文件前，需要将其签出以确保无人对其进行更改。 更新后，应签回文件，以便其他人能够使用它。
下面的示例展示了如何签出文件。
POST https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')/CheckOut(),
Authorization: "Bearer " + accessToken
X-RequestDigest: "{form_digest_value}"
下面的示例展示了如何签入文件。
POST https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')/CheckIn(comment='Comment',checkintype=0)
Authorization: "Bearer " + accessToken
X-RequestDigest: "{form_digest_value}"
下面的示例展示了如何删除文件。
POST https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')
Authorization: "Bearer " + accessToken
If-Match: "{etag or *}"
X-HTTP-Method: "DELETE"
X-RequestDigest: "{form_digest_value}"
使用 REST 处理大型文件
如果需要上传大于 1.5 兆字节 (MB) 的二进制文件，只能使用 REST 接口。 为获取代码示例，了解如何使用 SharePoint JavaScript 对象模型上传小于 1.5 MB 的二进制文件，请参阅在 SharePoint 中使用 JavaScript 库代码完成基本操作。 使用 REST 可创建的最大二进制文件为 2GB。
下面的示例展示了如何创建大型二进制文件。
警告
此方法只适用于 Internet Explorer 10 和其他最新版浏览器。
POST https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files/Add(url='{file_name}', overwrite=true)
Authorization: "Bearer " + accessToken
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"
Contents of binary file
下面的代码示例展示了如何使用此 REST 终结点和 JSOM 跨域库创建文件。
function uploadFileBinary() {
XDomainTestHelper.clearLog();
var requestExecutor;
if (document.getElementById("TxtViaUrl").value.length > 0) {
requestExecutor = new SP.RequestExecutor(document.getElementById("TxtWebUrl").value, document.getElementById("TxtViaUrl").value);
}
else {
requestExecutor = new SP.RequestExecutor(document.getElementById("TxtWebUrl").value);
}
var body = "";
for (var i = 0; i < 1000; i++) {
var ch = i % 256;
body = body + String.fromCharCode(ch);
}
var info = {
url: "_api/web/lists/getByTitle('Shared Documents')/RootFolder/Files/Add(url='a.dat', overwrite=true)",
method: "POST",
binaryStringRequestBody: true,
body: body,
success: success,
error: fail,
state: "Update"
};
requestExecutor.executeAsync(info);
}
使用 REST 处理附加到列表项的文件
下面的示例展示了如何检索附加到列表项的所有文件。
GET https://{site_url}/_api/web/lists/getbytitle('{list_title}')/items({item_id})/AttachmentFiles/
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
下面的示例展示了如何检索附加到列表项的特定文件。
GET https://{site_url}/_api/web/lists/getbytitle('{list_title}')/items({item_id})/AttachmentFiles('{file_name}')/$value
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
下面的示例展示了如何创建附加到列表项的文件。
POST https://{site_url}/_api/web/lists/getbytitle('{list_title}')/items({item_id})/AttachmentFiles/ add(FileName='{file_name}')
Authorization: "Bearer " + accessToken
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"
"Contents of file"
下面的示例展示了如何使用 PUT 方法更新附加到列表项的文件。
注意
PUT 是可用于更新文件的唯一方法。 不允许使用 MERGE 方法。
POST https://{site_url}/_api/web/lists/getbytitle('{list_title}')/items({item_id})/AttachmentFiles('{file_name}')/$value
Authorization: "Bearer " + accessToken
Content-Length: {length of request body as integer}
X-HTTP-Method: "PUT"
X-RequestDigest: "{form_digest_value}"
"Contents of file"