Работа с папками и файлами в службе RESTWorking with folders and files with REST

Совет

Служба REST в SharePoint Online (а также локальной среде SharePoint 2016 или более поздней версии) поддерживает объединение нескольких запросов в один вызов службы с помощью параметра запроса OData $batch.The SharePoint Online (and on-premises SharePoint 2016 and later) REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. Подробные сведения и ссылки на примеры кода см. в статье Отправка пакетных запросов с помощью интерфейсов REST API.For details and links to code samples, see Make batch requests with the REST APIs.

Работа с папками при помощи RESTWorking with folders by using REST

Вы можете получить папку в библиотеке документов, если знаете ее URL-адрес.You can retrieve a folder inside a document library when you know its URL. Например, можно получить корневую папку библиотеки Shared Documents, используя в следующем примере конечную точку.For example, you can retrieve the root folder of your Shared Documents library by using the endpoint in the following example.

GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Shared Documents')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

Ниже показан пример свойств папки, которые возвращаются при запросе типа контента XML.The following XML shows an example of folder properties that are returned when you request the XML content type.

<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>

В приведенном ниже примере показано, как создать папку.The following example shows how to create a folder.

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.The following example shows how to rename a folder by using the MERGE method.

Сначала получите тип OData папки с помощью запроса GET.First, obtain the folder's OData type with a GET request.

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 (значение может отличаться в зависимости от конфигурации вашей библиотеки).From the result, obtain the odata.type value, such as SP.Data.Shared_x0020_DocumentsItem (the value may be different depending on your library configuration). Затем отправьте запрос MERGE:Then submit a MERGE request:

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"
}

В приведенном ниже примере показано, как удалить папку.The following example shows how to delete a folder.

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}"

Работа с файлами при помощи RESTWorking with files by using REST

В приведенном ниже примере показано, как получить все файлы в папке.The following example shows how to retrieve all of the files in a folder.

GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files
method: GET
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

В приведенном ниже примере показано, как получить определенный файл.The following example shows how to retrieve a specific file.

GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files('{file_name}')/$value
Authorization: "Bearer " + accessToken

Вы также можете получить файл, если знаете его URL-адрес, как показано в следующем примере.You can also retrieve a file when you know its URL, as in the following example.

GET https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name})/$value
Authorization: "Bearer " + accessToken

В следующем примере кода показано, как получить файл, когда вы знаете его URL-адрес, используя указанную выше конечную точку REST и C#.The following code sample shows how to retrieve a file when you know its URL by using the REST endpoint above and 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();
}

В приведенном ниже примере показано, как создать файл и добавить его в папку.The following example shows how to create a file and add it to a folder.

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.The following example shows how to update a file by using the PUT method.

Примечание

Обновлять файлы можно только с помощью метода PUT. Использовать метод MERGE запрещено.PUT is the only method that you can use to update a file. The MERGE method is not allowed.

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"

Если вы хотите обновить метаданные файла, необходимо создать конечную точку, которая получает файл как элемент списка.If you want to update a file's metadata, you have to construct an endpoint that reaches the file as a list item. Это возможно, так как каждая папка также является списком, а каждый файл — элементом списка.You can do this because each folder is also a list, and each file is also a list item. Создайте такую конечную точку: https://{site_url}/_api/web/lists/getbytitle('Documents')/items({item_id}).Construct an endpoint that looks like this: https://{site_url}/_api/web/lists/getbytitle('Documents')/items({item_id}). Информацию о том, как обновить метаданные элемента списка, см. в статье Работа со списками и элементами списков в службе REST.For information about how to update a list item's metadata, see Working with lists and list items with REST.

Извлеките файл, чтобы никто не смог его изменить, прежде чем вы обновите его.You may want to check out a file to make sure that no one changes it before you update it. После обновления файл необходимо вернуть, чтобы другие пользователи могли с ним работать.After your update, you should check the file back in so that others can work with it.

В приведенном ниже примере показано, как извлечь файл.The following example shows how to check out a file.

POST https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')/CheckOut(),
Authorization: "Bearer " + accessToken
X-RequestDigest: "{form_digest_value}"

В приведенном ниже примере показано, как вернуть файл.The following example shows how to check in a file.

POST https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')/CheckIn(comment='Comment',checkintype=0)
Authorization: "Bearer " + accessToken
X-RequestDigest: "{form_digest_value}"

В приведенном ниже примере показано, как удалить файл.The following example shows how to delete a file.

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}"

Работа с большими файлами при помощи RESTWorking with large files by using REST

Отправить двоичный файл размером более 1,5 МБ можно только с помощью интерфейса REST.When you need to upload a binary file that is larger than 1.5 megabytes (MB), the REST interface is your only option. Пример кода для отправки двоичного файла размером менее 1,5 МБ с помощью объектной модели JavaScript SharePoint см. в статье Выполнение базовых операций с использованием кода библиотеки JavaScript в SharePoint.For a code example that shows you how to upload a binary file that is smaller than 1.5 MB by using the SharePoint JavaScript object model, see Complete basic operations using JavaScript library code in SharePoint. Максимальный размер двоичного файла, который можно создать с помощью REST, составляет 2 ГБ.The maximum size of a binary file that you can create with REST is 2 gigabytes (GB).

В приведенном ниже примере показано, как создать большой двоичный файл.The following example shows how to create a large binary file.

Предупреждение

Этот способ работает только в Internet Explorer 10 и последних версиях других браузеров.This approach works only with Internet Explorer 10 and the latest versions of other browsers.

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.The following code sample shows how to create a file by using this REST endpoint and the JSOM cross-domain library.

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);
}

Работа со вложенными в элементы списка файлами при помощи RESTWorking with files attached to list items by using REST

В приведенном ниже примере показано, как получить все файлы, вложенные в элемент списка.The following example shows how to retrieve all of the files that are attached to a list item.

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

В приведенном ниже примере показано, как получить файл, вложенный в элемент списка.The following example shows how to retrieve a file that is attached to a list item.

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"

В приведенном ниже примере показано, как создать вложение в элемент списка.The following example shows how to create a file attachment to a list item.

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.The following example shows how to update a file attachment to a list item by using the PUT method.

Примечание

Обновлять файлы можно только с помощью метода PUT. Использовать метод MERGE запрещено.PUT is the only method that you can use to update a file. The MERGE method is not allowed.

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"

См. такжеSee also