Arbeiten mit Ordnern und Dateien unter Verwendung von REST

  • Artikel

Hinweis

Die Beispiele auf dieser Seite unterstützen die Zeichen % und # nicht. Unterstützen von % und # in Dateien und Ordnern mit der ResourcePath-API

Tipp

Der SharePoint Online-REST-Dienst (und lokale SharePoint 2016 und höher) unterstützt das Kombinieren mehrerer Anforderungen in einem einzigen Aufruf des Diensts mithilfe der OData-Abfrageoption $batch . Einzelheiten und Links zu Codebeispielen finden Sie unter Durchführen von Batchanforderungen mit den REST-APIs.

Arbeiten mit Ordnern unter Verwendung von REST

Sie können einen Ordner innerhalb einer Dokumentbibliothek abrufen, wenn Sie die URL des Ordners kennen. Beispielsweise können Sie den Stammordner Ihrer Bibliothek für freigegebene Dokumente mithilfe des Endpunkts im folgenden Beispiel abrufen.

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

Der folgende XML-Code zeigt ein Beispiel für die Ordnereigenschaften, die beim Anfordern des XML-Inhaltstyps zurückgegeben werden.

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

Das folgende Beispiel zeigt, wie Sie einen Ordner erstellen.

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

Das folgende Beispiel zeigt, wie Sie einen Ordner mit der MERGE-Methode umbenennen.

Ermitteln Sie zunächst den OData-Typ des Ordners mit einer GET-Anforderung.

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

Ermitteln Sie aus dem Ergebnis den odata.type-Wert, z. B. SP.Data.Shared_x0020_DocumentsItem (der Wert kann abhängig von der Konfiguration Ihrer Bibliothek unterschiedlich sein). Senden Sie dann eine MERGE-Anforderung:

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

Das folgende Beispiel zeigt, wie Sie einen Ordner löschen.

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

Arbeiten mit Dateien unter Verwendung von REST

Das folgende Beispiel zeigt, wie Sie alle Dateien in einem Ordner abrufen.

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

Das folgende Beispiel zeigt, wie Sie eine bestimmte Datei abrufen.

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

Sie können eine Datei auch abrufen, wenn Sie ihre URL kennen, wie im folgenden Beispiel gezeigt.

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

Das folgende Codebeispiel zeigt, wie Sie eine Datei abrufen, wenn Sie deren URL kennen, und dazu den oben aufgeführten REST-Endpunkt sowie C# verwenden.

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

Das folgende Beispiel zeigt, wie Sie eine Datei erstellen und zu einem Ordner hinzufügen.

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"

Das folgende Beispiel zeigt, wie Sie eine Datei aktualisieren und dazu die PUT-Methode verwenden.

Hinweis

PUT ist die einzige Methode, die Sie zum Aktualisieren einer Datei verwenden können. DieMERGE-Methode ist nicht zulässig.

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"

Wenn Sie die Metadaten einer Datei aktualisieren möchten, müssen Sie einen Endpunkt erstellen, der die Datei als ein Listenelement erreicht. Dies ist möglich, da jeder Ordner auch eine Liste ist, und jede Datei auch ein Listenelement. Erstellen Sie einen Endpunkt, der in etwa so aussieht: https://{site_url}/_api/web/lists/getbytitle('Documents')/items({item_id}). Weitere Informationen zum Aktualisieren der Metadaten eines Listenelements finden Sie unter Arbeiten mit Listen und Listenelementen mit REST.

Sie können eine Datei auschecken, um sicherzustellen, dass niemand sie ändert, bevor Sie sie aktualisieren. Nach der Aktualisierung sollten Sie die Datei wieder einchecken, sodass andere wieder damit arbeiten können.

Das folgende Beispiel zeigt, wie Sie eine Datei auschecken.

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

Das folgende Beispiel zeigt, wie Sie eine Datei einchecken.

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

Das folgende Beispiel zeigt, wie Sie eine Datei löschen.

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

Arbeiten mit großen Dateien unter Verwendung von REST

Wenn Sie eine Binärdatei hochladen möchten, die größer als 1,5 Megabyte (MB) ist, ist die REST-Schnittstelle die einzige Option. Unter Ausführen grundlegender Vorgänge unter Verwendung von JavaScript-Bibliothekscode in SharePoint finden Sie ein Codebeispiel, in dem gezeigt wird, wie Sie eine binäre Datei mit einer Größe unter 1,5 MB mithilfe des SharePoint Javascript-Objektmodells hochladen. Die maximale Größe einer Binärdatei, die Sie mit REST erstellen können, ist 2 Gigabyte (GB).

Das folgende Beispiel zeigt, wie Sie eine große Binärdatei erstellen.

Warnung

Diese Vorgehensweise funktioniert nur mit Internet Explorer 10 und den neuesten Versionen anderer Browser.

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

Im folgenden Codebeispiel wird gezeigt, wie Sie eine Datei mit diesem REST-Endpunkt und der domänenübergreifenden JSOM-Bibliothek erstellen.

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

Arbeiten mit an Listenelemente angefügten Dateien mithilfe von REST

Das folgende Beispiel zeigt, wie Sie alle an ein Listenelement angefügten Dateien abrufen.

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

Das folgende Beispiel zeigt, wie Sie eine an ein Listenelement angefügte Datei abrufen.

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"

Das folgende Beispiel zeigt, wie Sie eine an ein Listenelement angefügte Datei erstellen.

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"

Das folgende Beispiel zeigt, wie Sie eine an ein Listenelement angefügte Datei erstellen und dabei die Methode PUT verwenden.

Hinweis

PUT ist die einzige Methode, die Sie zum Aktualisieren einer Datei verwenden können. DieMERGE-Methode ist nicht zulässig.

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"

Siehe auch