Trabalhar com pastas e arquivos com REST

  • Artigo

Observação

Os exemplos desta página não têm suporte os caracteres % e #. Suporte a % e # em arquivos e pastas com a API ResourcePath

Dica

O serviço REST do SharePoint Online (e o SharePoint 2016 e posterior no local) dá suporte à combinação de várias solicitações em uma única chamada para o serviço usando a opção de consulta $batch do OData. Para obter detalhes e links de amostras de código, confira Fazer solicitações em lote com APIs REST.

Trabalhar com pastas usando REST

Você pode recuperar uma pasta dentro de uma biblioteca de documentos quando sabe a URL dela. Por exemplo, é possível recuperar a pasta raiz da sua biblioteca de documentos compartilhados usando o ponto de extremidade no exemplo a seguir.

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

O XML a seguir mostra um exemplo das propriedades de pasta retornadas quando você solicita o tipo de conteúdo 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>

O exemplo a seguir mostra como criar uma pasta.

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

O exemplo a seguir mostra como renomear uma pasta usando o método MERGE.

Primeiro, obtenha o tipo OData da pasta com uma solicitação GET.

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

A partir do resultado, obtenha o valor de odata.type, como SP.Data.Shared_x0020_DocumentsItem (o valor pode ser diferente dependendo da configuração da biblioteca). Em seguida, envie uma solicitação 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"
}

O exemplo a seguir mostra como excluir uma pasta.

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

Trabalhar com arquivos usando o REST

O exemplo a seguir mostra como recuperar todos os arquivos em uma pasta.

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

O exemplo a seguir mostra como recuperar um arquivo específico.

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

Você também pode recuperar um arquivo quando sabe a URL dele, como no exemplo a seguir.

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

O exemplo a seguir mostra como recuperar um arquivo quando você sabe a URL dele, usando o ponto de extremidade REST acima e 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();
}

O exemplo a seguir mostra como criar um arquivo e adicioná-lo a uma pasta.

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"

O exemplo a seguir mostra como atualizar um arquivo usando o método PUT.

Observação

PUT é o único método que você pode usar para atualizar um arquivo. O método MERGE não é permitido.

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"

Se você quiser atualizar os metadados de um arquivo, terá que construir um ponto de extremidade que atinja o arquivo como um item de lista. Você pode fazer isso porque cada pasta também é uma lista, e cada arquivo também é um item de lista. Construa um ponto de extremidade assim: https://{site_url}/_api/web/lists/getbytitle('Documents')/items({item_id}). Para saber mais sobre como atualizar os metadados de um item de lista, confira Trabalhar com listas e itens de lista com REST.

Convém fazer check-out de um arquivo para garantir que ninguém o altere antes de você atualizá-lo. Após atualizar, você deve fazer check-in do arquivo novamente para que outras pessoas possam trabalhar com ele.

O exemplo a seguir mostra como fazer check-out de um arquivo.

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

O exemplo a seguir mostra como fazer check-in de um arquivo.

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

O exemplo a seguir mostra como excluir um arquivo.

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

Trabalhar com arquivos grandes usando REST

Quando você precisa carregar um arquivo binário maior que 1,5 MB (megabytes), a interface REST é sua única opção. Para ver um código de exemplo que mostra como carregar um arquivo binário menor que 1,5 MB usando o modelo de objeto Javascript do SharePoint, confira Realizar operações básicas usando código de biblioteca JavaScript no SharePoint. O tamanho máximo de um arquivo binário que você pode criar com o REST é de 2 GB (gigabytes).

O exemplo a seguir mostra como criar um arquivo binário grande.

Aviso

Essa abordagem só funciona com o Internet Explorer 10 e as versões mais recentes de outros navegadores.

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

O exemplo a seguir mostra como criar um arquivo usando esse ponto de extremidade REST e a biblioteca entre domínios 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);
}

Trabalhar com arquivos anexados a itens de lista usando REST

O exemplo a seguir mostra como recuperar todos os arquivos anexados a um item de lista.

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

O exemplo a seguir mostra como recuperar um arquivo anexado a um item de lista.

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"

O exemplo a seguir mostra como criar um anexo de arquivo para um item de lista.

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"

O exemplo a seguir mostra como atualizar um anexo de arquivo para um item de lista usando o método PUT.

Observação

PUT é o único método que você pode usar para atualizar um arquivo. O método MERGE não é permitido.

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"

Confira também