Navigieren in der im REST-Dienst dargestellten SharePoint-Datenstruktur

  • Artikel

Beim Arbeiten mit dem SharePoint REST-Dienst kennen Sie oft die URL eines bestimmten SharePoint-Elements und möchten auf dazugehörige Elemente zugreifen, z. B. den Ordner oder die Struktur der Bibliothek, unter der sich das Element befindet. Angenommen Sie erstellen z. B. ein Add-in, bei dem der Benutzer die URL eines Dokuments in einer SharePoint-Bibliothek eingeben kann. Das Add-in muss die URL aufschlüsseln, um die URL der eigentlichen SharePoint-Website zu finden. Danach können von der Website aus im Namen des Benutzers von dem Add-in weitere Anforderungen vorgenommen werden, z. B. zum Erstellen, Aktualisieren oder Löschen zugehöriger Elemente oder Ressourcen.

Zu diesem Zweck muss das Add-in folgende Informationen von SharePoint abfragen:

  • Die relativen Server-URLs der Website und die Websitesammlung, welche die Ressource enthält.
  • Ein Formulardigest, mit dem Sie Abfragen ausführen können, die den Status der Ressource ändern. Beispiel: POST, PUT, MERGE und DELETE.

Das grundlegende Verfahren

  1. Verwenden Sie den Operator /contextinfo mit der angegebenen URL, um auf die Adressen der Website und der Websitesammlung und den Formulardigest zuzugreifen. Verwenden Sie den Operator /contextinfo in folgendem Format:

    POST https://{site_url}/_api/contextinfo
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

    Zur Verbesserung der Sicherheit gegenüber websiteübergreifenden Scriptingversuchen akzeptiert der Operator /contextinfo nur POST-Anforderungen.

  2. Verwenden Sie für den Zugriff auf zusätzliche Ressourcen bei Bedarf die Objekteigenschaften SPContextWebInformation, die der Operator /contextinfo zurückgibt.

Ausprobieren

  1. Starten Sie mit einer URL eines gegebenen SharePoint-Elements. Beispiel: https://{site_url}/doclib/myDocument.docx

  2. Entfernen Sie den Namen der spezifischen Ressource vom Ende der URL, damit die URL auf eine Dokumentbibliothek, einen Ordner oder eine Liste verweist. In diesem Fall: https://{site_url}/doclib/

  3. Fügen Sie den Zeiger des REST-Dienstes und den Operator /contextinfo an die URL an:

    POST https://{site_url}/_api/doclib/contextinfo
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

  4. Lesen Sie den Formulardigest und die Eigenschaften WebFullUrl aus der Antwort aus.

  5. Fügen Sie den Zeiger des REST-Dienstes _api an die Web-URL an.

  6. Verwenden Sie die resultierende URL und den Formulardigest für Anforderungen nach anderen Ressourcen, die Sie benötigen.

Tipp

Sie müssen den Formulardigest nicht übergeben, wenn Sie GET-Anforderungen oder Anforderungen mit einem überprüften OAuth-Token ausführen möchten.

Wenn Sie mithilfe des SharePoint Serverobjektmodells durch die Websitestruktur navigieren, verwenden Sie für den Zugriff auf Objekte, die übergeordnete und untergeordnete Websites darstellen, die Eigenschaften SPWeb.ParentWeb und SPWeb.Webs.

Die entsprechenden REST-Ressourcen, web/parentweb und web/webs, geben keine Objekte zurück, die Websites darstellen. Der Grund dafür ist, dass der REST-Dienst OData-Standards entspricht und solche Anforderungen durch das Zurückgeben vollständiger Websitedarstellungen ineffizient würden. Stattdessen geben sie ein WebInfo-Objekt mit den skalaren Eigenschaften der Website, aber ohne zugehörige Entitätensätze wie Sammlungen oder Feldsammlungen zurück.

Um zu einer bestimmten übergeordneten oder untergeordneten Website zu navigieren, erstellen Sie die entsprechende REST-URL zu dieser Website, indem Sie Id oder Title verwenden. Hier können Sie auf die mit der Website verknüpften Entitätenmengen zugreifen.

Der SharePoint REST-Dienst bietet keine Unterstützung für das Durchsuchen der Ordnerhierarchie einer Website über die URL-Konstruktion. Verwenden Sie stattdessen das REST-Äquivalent der Methode Web.GetFolderByServerRelativeUrl. Beispiel:

Durch den REST-Dienst nicht unterstützte Navigation:

https://{site_url}/_vti_bin/client.svc/web/lists/SharedDocuments/folder1/stuff/things/Recycle

Durch den REST-Dienst unterstützte Navigation:

https://{site_url}/_vti_bin/client.svc/web/GetFolderByServerRelativeUrl('SharedDocuments/folder1/stuff/things')/Recycle

SPContextWebInformation-Objekteigenschaften

Eigenschaft SPContextWebInformation Beschreibung
webFullUrl Ruft die serverrelative URL der nächstgelegenen Website ab.
siteFullUrl Ruft die relative Server-URL von der Stammebene der erstellten Websitesammlung ab, in der die Website enthalten ist.
Wenn der Stamm einer Websitesammlung am nächsten gelegen ist, dann entspricht der Wert der Eigenschaft webFullUrl der Eigenschaft siteFullUrl.
formDigestValue Ruft den Formulardigest der Serveranforderung ab.
LibraryVersion Ruft die aktuelle Version der REST-Bibliothek ab.
SupportedSchemaVersions Ruft die Versionen des Schemas der REST-/CSOM-Bibliothek ab, die unterstützt werden.

WebInfo-Objekt

WebInfo-Eigenschaft Beschreibung
Created Ruft einen Wert ab, der angibt, wann die Website erstellt wurde.
Beschreibung Dient zum Abrufen oder Festlegen der Beschreibung der Website.
Id Ruft einen Wert ab, der den Websitebezeichner angibt.
Language Ruft einen Wert ab, der die Gebietsschema-ID (LCID) für die Sprache angibt, die auf der Website verwendet wird.
LastItemModifiedDate Ruft einen Wert ab, der angibt, wann ein Element auf der Website zuletzt geändert wurde.
Title Dient zum Abrufen oder Festlegen des Titels der Website.
WebTemplateId Ruft den Bezeichner der Websitevorlage ab.

Siehe auch