Trabajar con carpetas y archivos con REST

  • Artículo

Nota:

Los ejemplos de esta página no admiten los caracteres % y #. Soporte de % y # en archivos y carpetas con la API ResourcePath

Sugerencia

El servicio REST de SharePoint Online (y SharePoint 2016 local y versiones posteriores) admite la combinación de varias solicitudes en una sola llamada al servicio mediante la opción de consulta OData $batch . Para obtener información detallada y vínculos a los ejemplos de código, vea Realizar solicitudes de lote con las API de REST.

Trabajar con carpetas mediante REST

Puede recuperar una carpeta de una biblioteca de documentos cuando conoce su dirección URL. Por ejemplo, puede recuperar la carpeta raíz de la biblioteca de documentos compartidos usando el punto de conexión del ejemplo siguiente.

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

El XML siguiente muestra un ejemplo de las propiedades de carpeta que se devuelven cuando solicita el tipo de contenido 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>

En el siguiente ejemplo, se muestra cómo crear una carpeta.

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

En el siguiente ejemplo, se muestra cómo renombrar una carpeta usando el método MERGE.

En primer lugar, obtenga el tipo de OData de la carpeta con una solicitud GET.

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

A partir del resultado, obtenga el valor odata.type, como SP.Data.Shared_x0020_DocumentsItem (el valor puede ser diferente según la configuración de la biblioteca). Después, envíe una solicitud 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"
}

En el siguiente ejemplo se muestra cómo eliminar una carpeta.

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

Trabajar con archivos mediante REST

En el siguiente ejemplo se muestra cómo recuperar todos los archivos de una carpeta.

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

En el siguiente ejemplo, se muestra cómo recuperar un archivo específico.

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

También puede recuperar un archivo cuando conoce su URL, como en el ejemplo siguiente.

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

El siguiente ejemplo de código muestra cómo recuperar un archivo cuando conoce su URL utilizando el punto de conexión REST anterior y 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();
}

En el siguiente ejemplo, se muestra cómo crear un archivo y agregarlo a una carpeta.

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"

En el siguiente ejemplo se muestra cómo actualizar un archivo con el método PUT.

Nota:

PUT es el único método que puede usar para actualizar un archivo. No se permite el método 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"

Si quiere actualizar los metadatos de un archivo, tiene que crear un punto de conexión que llegue al archivo como elemento de lista. Esto puede hacerse porque cada carpeta es también una lista y cada archivo es también un elemento de lista. Cree un punto de conexión que tenga el siguiente aspecto: https://{site_url}/_api/web/lists/getbytitle('Documents')/items({item_id}). Para obtener información sobre cómo actualizar los metadatos de un elemento de lista, vea Trabajar con listas y elementos de lista con REST.

Puede que quiera extraer un archivo del repositorio para asegurarse de que nadie lo cambie antes de que lo actualice. Tras la actualización, debe volver a insertarlo en el repositorio para que otros usuarios puedan trabajar con él.

En el siguiente ejemplo se muestra cómo extraer del repositorio un archivo.

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

En el siguiente ejemplo se muestra cómo insertar en el repositorio un archivo.

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

En el siguiente ejemplo se muestra cómo eliminar un archivo.

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

Trabajar con archivos de gran tamaño mediante REST

Si tiene que cargar un archivo binario de más de 1,5 megabytes (MB), la interfaz de REST es su única opción. Para obtener un ejemplo de código que le muestra cómo cargar un archivo binario de menos de 1,5 MB mediante el modelo de objetos JavaScript de SharePoint, vea Completar operaciones básicas con código de biblioteca de JavaScript en SharePoint. El tamaño máximo del archivo binario que se puede crear con REST es de 2 gigabytes (GB).

En el siguiente ejemplo se ve cómo crear un archivo binario de gran tamaño.

Advertencia

Este enfoque solo funciona con Internet Explorer 10 y las últimas versiones de otros exploradores.

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

En el siguiente ejemplo de código se muestra cómo crear un archivo mediante este punto de conexión de REST y la biblioteca entre dominios de 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);
}

Trabajar con archivos adjuntos a elementos de lista mediante REST

En el siguiente ejemplo se muestra cómo recuperar todos los archivos adjuntos a un elemento de lista.

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

En el siguiente ejemplo, se muestra cómo recuperar un archivo que está adjunto a un elemento 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"

En el siguiente ejemplo, se muestra cómo crear un archivo adjunto a un elemento 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"

En el siguiente ejemplo se muestra cómo actualizar un archivo adjunto a un elemento de lista mediante el método PUT.

Nota:

PUT es el único método que puede usar para actualizar un archivo. No se permite el método 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"

Vea también