Utilisation des dossiers et des fichiers avec REST

  • Article

Remarque

Les exemples sur cette page ne prennent pas en charge les caractères % et #. Prise en charge de % et # dans les fichiers et dossiers avec l’API ResourcePath

Conseil

Le service REST SharePoint Online (et SharePoint sur site 2016 et ultérieur) prend en charge la combinaison de plusieurs requêtes en un seul appel au service à l’aide de l’option de requête $batch OData. Pour obtenir plus d’informations et des liens vers des exemples de code, consultez la rubrique Créer des requêtes de lots avec l’API REST.

Utiliser des dossiers à l’aide de REST

Vous pouvez récupérer un dossier à l’intérieur d’une bibliothèque de documents si vous en connaissez l’URL. Par exemple, vous pouvez récupérer le dossier racine de votre bibliothèque Documents partagés à l’aide du point de terminaison fourni dans l’exemple suivant.

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

Le code XML ci-après présente un exemple des propriétés de dossier qui sont renvoyées lorsque vous demandez le type de contenu 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>

L’exemple suivant montre comment créer un dossier.

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

L’exemple suivant montre comment renommer un dossier à l’aide de la méthode MERGE.

Tout d’abord, obtenez le type OData du dossier avec une requête GET.

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

À partir du résultat, obtenez la valeur odata.type, par exemple, SP.Data.Shared_x0020_DocumentsItem (la valeur peut varier en fonction de la configuration de votre bibliothèque). Envoyez ensuite une demande 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"
}

L’exemple suivant montre comment supprimer un dossier.

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

Utilisation de fichiers à l’aide de l’interface REST

L’exemple suivant montre comment récupérer tous les fichiers d’un dossier.

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

L’exemple suivant montre comment récupérer un fichier spécifique.

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

Vous pouvez également récupérer un fichier lorsque vous en connaissiez l’URL, comme dans l’exemple ci-après.

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

L’exemple de code suivant montre comment récupérer un fichier dont vous connaissez l’URL en utilisant le point de terminaison REST ci-dessus et 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();
}

L’exemple suivant montre comment créer un fichier et l’ajouter à un dossier.

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"

L’exemple suivant montre comment mettre à jour un fichier à l’aide de la méthode PUT.

Remarque

PUT est la seule méthode permettant de mettre à jour un fichier. La méthode MERGE n’est pas autorisée.

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"

Pour mettre à jour les métadonnées d’un fichier, créez un point de terminaison qui atteint le fichier en tant qu’élément de liste. Vous pouvez effectuer cette action parce que chaque dossier est également une liste, et que chaque fichier est également un élément de liste. Créez un point de terminaison qui ressemble à ceci : https://{site_url}/_api/web/lists/getbytitle('Documents')/items({item_id}). Pour en savoir plus sur la mise à jour des métadonnées d’un élément de liste, consultez l’article Utilisation d’une liste et de ses éléments avec REST.

Il peut être utile d’extraire un fichier pour vous assurer que personne ne le modifie avant que vous ne le mettiez à jour. Après votre mise à jour, il est également conseillé de ré-archiver le fichier pour que d’autres utilisateurs puissent travailler dessus.

L’exemple suivant montre comment extraire un fichier.

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

L’exemple suivant montre comment archiver un fichier.

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

L’exemple suivant montre comment supprimer un fichier.

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

Utilisation de fichiers volumineux à l’aide de REST

Si vous devez charger un fichier binaire supérieur à 1,5 mégaoctet (Mo), l’interface REST est la seule option disponible. Pour obtenir un exemple de code qui vous montre comment charger un fichier binaire inférieur à 1,5 Mo à l’aide du modèle objet Javascript SharePoint, consultez l’article Effectuer des opérations de base avec du code de bibliothèque JavaScript dans SharePoint. La taille maximale d’un fichier binaire que vous pouvez créer avec REST est de 2 gigaoctets (Go).

L’exemple suivant montre comment créer un fichier binaire volumineux.

Avertissement

Cette approche ne fonctionne qu’avec Internet Explorer 10 et les versions les plus récentes des autres navigateurs.

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

L’exemple de code suivant montre comment créer un fichier à l’aide de ce point de terminaison REST et de la bibliothèque inter-domaines 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);
}

Utilisation de fichiers joints à des éléments de liste à l’aide de REST

L’exemple suivant montre comment récupérer tous les fichiers joints à un élément de liste.

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

L’exemple suivant montre comment récupérer un fichier joint à un élément de liste.

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"

L’exemple suivant montre comment créer une pièce jointe associée à un élément de liste.

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"

L’exemple suivant montre comment mettre à jour une pièce jointe associée à un élément de liste à l’aide de la méthode PUT.

Remarque

PUT est la seule méthode permettant de mettre à jour un fichier. La méthode MERGE n’est pas autorisée.

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"

Voir aussi