Grundlegendes zum SharePoint REST-Dienst

SharePoint enthält einen REST-Dienst (Representational State Transfer), der mit den bestehenden SharePoint Clientobjektmodellen vergleichbar ist. Entwickler können nun über eine beliebige Technologie, die REST-Webanforderungen unterstützt, remote mit SharePoint-Daten interagieren. Dies bedeutet, dass Entwickler mithilfe von REST-Webtechnologien und der standardmäßigen Open Data Protocol(OData)-Syntax über SharePoint-Add-Ins, -Lösungen und -Clientanwendungen CRUD-Vorgänge (Erstellen, Lesen, Aktualisieren und Löschen) ausführen können.

Voraussetzungen

In diesem Thema wird davon ausgegangen, dass Sie über grundlegende Kenntnisse in REST und im Erstellen von REST-Anfragen verfügen.

Funktionsweise des SharePoint REST-Diensts

In SharePoint wurde die Möglichkeit hinzugefügt, mithilfe von REST remote mit SharePoint-Websites zu interagieren. Sie können jetzt mithilfe jeder Technologie, die standardmäßige REST-Funktionen unterstützt, direkt mit SharePoint-Objekten interagieren.

Um mithilfe von REST auf SharePoint-Ressourcen zuzugreifen, erstellen Sie mithilfe des OData-Standards (Open Data Protocol), das der gewünschten Clientobjektmodell-API entspricht, eine RESTful-HTTP-Anforderung. Beispiel: Zum Beispiel:

CSOM

var items = List.GetByTitle(listname).GetItems();

http

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

Der Webdienst „client.svc“ in SharePoint verarbeitet die HTTP-Anforderung und liefert die entsprechende Antwort entweder im Atom- oder im JavaScript Object Notation (JSON)-Format. Die Clientanwendung muss diese Antwort dann analysieren. Die folgende Abbildung zeigt eine allgemeine Übersicht über die SharePoint-REST-Architektur.

Architektur des SharePoint REST-Diensts

Aufgrund ihrer Funktionen und Benutzerfreundlichkeit bleiben Clientobjektmodelle die erste Entwicklungsoption für die Kommunikation mit SharePoint-Websites mithilfe von .NET Framework, Silverlight (jetzt eingestellt) oder JavaScript (JSOM).

Verwenden von HTTP-Befehlen im SharePoint REST-Dienst

Um die in SharePoint integrierten REST-Funktionen zu verwenden, erstellen Sie mithilfe des OData-Standards eine RESTful-HTTP-Anforderung, die der Clientobjektmodell-API entspricht, die Sie verwenden möchten. Der Webdienst „client.svc“ verarbeitet die HTTP-Anforderung und liefert die entsprechende Antwort im Format Atom oder JSON. Die Clientanwendung muss diese Antwort dann analysieren.

Die Endpunkte im SharePoint-REST-Dienst entsprechen den Typen und Membern in den SharePoint-Clientobjektmodellen. Mithilfe von HTTP-Anforderungen können Sie diese REST-Endpunkte verwenden, um typische CRUD-Vorgänge für SharePoint-Entitäten wie Listen und Websites durchzuführen.

Wenn Sie dies an einem Endpunkt ausführen möchten	Verwenden Sie diese HTTP-Anforderung	Zu berücksichtigen
Lesen einer Ressource	GET
Erstellen oder Aktualisieren einer Ressource	POST	Verwenden Sie POST, um Entitäten wie Listen und Websites zu erstellen. Der SharePoint-REST-Dienst unterstützt das Senden von POST-Befehlen, die Objektdefinitionen enthalten, an Endpunkte, die Sammlungen darstellen. Bei POST-Vorgängen werden alle Eigenschaften, die nicht erforderlich sind, auf ihre Standardwerte festgelegt. Wenn Sie versuchen, eine schreibgeschützte Eigenschaft als Teil des POST-Vorgangs festzulegen, gibt der Dienst eine Ausnahme zurück.
Aktualisieren oder Hinzufügen einer Ressource	PUT	Verwenden Sie PUT- und MERGE-Vorgänge, um vorhandene SharePoint-Objekte zu aktualisieren. Jeder Dienstendpunkt, der einen set-Vorgang einer Objekteigenschaft darstellt, unterstützt sowohl PUT- als auch MERGE-Anforderungen. Bei MERGE-Vorgängen ist das Festlegen von Eigenschaften optional; Eigenschaften, die Sie nicht explizit festlegen, behalten ihre aktuelle Eigenschaft. Wenn Sie bei PUT-Befehlen nicht alle erforderlichen Eigenschaften in Objektaktualisierungen angeben, gibt der REST-Dienst eine Ausnahme zurück. Zusätzlich werden alle nicht explizit angegebenen Eigenschaften auf ihre Standardeigenschaften festgelegt.
Löschen einer Ressource	DELETE	Verwenden Sie den DELETE-HTTP-Befehl für die entsprechende Endpunkt-URL, um das von diesem Endpunkt dargestellte SharePoint-Objekt zu löschen. Bei wiederverwendbaren Objekten, z. B. Listen, Dateien und Listenelementen, führt dies zu einer Recycle-Operation.

Erstellen von REST URLs für den Zugriff auf SharePoint-Ressourcen

Wann immer möglich, bildet die URI für diese REST-Endpunkte die API-Signatur der Ressource im SharePoint-Clientobjektmodell streng nach. Die zentralen Einstiegspunkte für den REST-Service stellen die Websitesammlung und die Website des angegebenen Kontexts dar.

Gehen Sie folgendermaßen vor, um auf eine bestimmte Websitesammlung zuzugreifen:

https://{site_url}/_api/site

Gehen Sie folgendermaßen vor, um auf eine bestimmte Website zuzugreifen:

https://{site_url}/_api/web

Dabei steht server für den Namen des Servers und site für den Namen der oder den Pfad zur entsprechenden Website.

Ausgehend davon können Sie dann spezifischere REST-URIs erstellen, indem Sie das Objektmodell mithilfe der durch Schrägstrich (/) getrennten Namen der APIs aus dem Clientobjektmodell durchsuchen.

Diese Syntax gilt nicht für REST-APIs des SocialFeedManager oder SocialFollowingManager. Weitere Informationen finden Sie unter:

• REST-API-Referenz für sozialen Feed für SharePoint
• REST-API-Referenz zum Folgen von Personen und Inhalten für SharePoint

Unter Ermitteln von URIs von SharePoint-REST-Dienstendpunkten finden Sie Richtlinien zur Ermittlung von URIs von SharePoint-REST-Dienstendpunkten mithilfe der Signatur der entsprechenden Clientobjektmodell-APIs.

Beispiele für SharePoint REST-Endpunkte

Die folgende Tabelle enthält Beispiele für typische REST-Endpunkt-URLs, um Ihnen den Einstieg in die Arbeit mit SharePoint-Daten zu erleichtern. Stellen Sie den in der Tabelle gezeigten URL-Fragmenten http://server/site/_api/ voran, um eine vollständig qualifizierte REST-URL zu konstruieren. Wenn für POST-Befehle erforderlich, enthält die Tabelle Beispieldaten, die Sie im Hauptteil der HTTP-Anforderung übergeben müssen, um das angegebene SharePoint-Element zu erstellen. Elemente in Kursivschrift stellen Variablen dar, die Sie durch Ihre Werte ersetzen müssen.

Beschreibung	URL-Endpunkt	HTTP-Methode	Textkörper
Ruft den Titel einer Website ab	web/title	GET	–
Ruft alle Listen auf einer Website	lists	GET	Nicht zutreffend
Ruft die Metadaten einer einzelnen Liste ab	lists/getbytitle('listname')	GET	–
Ruft Elemente in einer Liste ab	lists/getbytitle('listname')/items	GET	Nicht zutreffend
Ruft eine bestimmte Eigenschaft einer Liste ab. (In diesem Fall den Titel der Liste)	lists/getbytitle('listname')?select=Title	GET	–
Erstellt eine Liste	lists	POST	Siehe Beispiel
Fügt einer Liste einen Eintrag hinzu.	lists/getbytitle('listname')/items	POST	Siehe Beispiel

Erstellt eine Liste Beispieldaten:

{
  "__metadata": {
    "type": "SP.List"
  },
  "AllowContentTypes": true,
  "BaseTemplate": 104 ,
  "ContentTypesEnabled": true,
  "Description": "My list description ",
  "Title": "RestTest "
}

Fügt ein Element zu einer Liste hinzu Beispieldaten:

{
  "__metadata": {
    "type": "SP.Data.listname.ListItem"
  },
  "Title": "MyItem"
}

Ersetzen Sie "listname" im vorstehenden JSON-Code durch den Namen Ihrer SharePoint-Liste, wobei Sie Leerzeichen weglassen.

Unterstützung für Batchaufträge

Der SharePoint Online-REST-Dienst (und der Dienst von SharePoint 2016 (lokal) oder höher) unterstützt die Kombination mehrerer Anforderungen in einem einzelnen Dienstaufruf mithilfe der OData-Abfrageoption $batch. Einzelheiten und Links zu Codebeispielen finden Sie unter Erstellen von Batchanforderungen mit den REST-APIs.

OData-Ressourcen

• Entwickeln von dienstorientierten Anwendungen mit WCF
• Open Data Protocol
• OData-Protokoll – URI-Konventionen
• Adressieren von Dienstvorgängen
• OData-Protokoll – Vorgänge
• Fehlerbedingungen

Themen zum SharePoint-REST-Dienst

Verwenden Sie die folgenden Ressourcen, um weitere Informationen zum Verwenden des SharePoint REST-Diensts zu erhalten.

Titel	Beschreibung
Ausführen grundlegender Vorgänge unter Verwendung von SharePoint REST-Endpunkten	Durchführen grundlegender Erstellungs-, Lese-, Aktualisierungs- und Löschoperationen, auch als CRUD-Operationen (Create, Read, Update, Delete) bezeichnet, mit der SharePoint-REST-Schnittstelle.
Arbeiten mit Listen und Listenelementen unter Verwendung von REST	Durchführen grundlegender Erstellungs-, Lese-, Aktualisierungs- und Löschoperationen, auch als CRUD-Operationen (Create, Read, Update, Delete) bezeichnet, für Listen und Listenelemente mit der SharePoint REST-Schnittstelle.
Arbeiten mit Ordnern und Dateien unter Verwendung von REST	Durchführen grundlegender Erstellungs-, Lese-, Aktualisierungs- und Löschoperationen, auch als CRUD-Operationen (Create, Read, Update, Delete) bezeichnet, für Ordner und Dateien mit der SharePoint REST-Schnittstelle.
Navigieren in der im REST-Dienst dargestellten SharePoint-Datenstruktur	Starten von einem REST-Endpunkt für einen gegebenen SharePoint-Element und Navigieren zu und Zugreifen auf dazugehörige Elemente, z. B. übergeordnete Standorte oder die Bibliotheksstruktur, in der sich das jeweilige Element befindet.
Ermitteln von URIs von SharePoint REST-Dienstendpunkten	Allgemeine Richtlinien zur Ermittlung von URIs von SharePoint-REST-Endpunkten mithilfe der Signatur der entsprechenden Clientobjektmodell-APIs.
Verwenden von OData-Abfragevorgängen in SharePoint REST-Anforderungen	Hier erfahren Sie, wie Sie eine Reihe von OData-Abfragezeichenfolgeoperatoren verwenden, um die vom SharePoint REST-Dienst angeforderten Daten auszuwählen, zu filtern und zu ordnen.
Durchführen von Batchanforderungen mit den REST-APIs	Erfahren Sie, wie Sie mehrere Anforderungen zu einem einzigen Aufruf an den REST-Dienst kombinieren.
Synchronisieren von SharePoint-Elementen mit dem REST-Dienst	Erfahren Sie, wie Sie mit der Ressource GetListItemChangesSinceToken, die Teil des SharePoint REST-Diensts ist, Elemente zwischen SharePoint und Ihren Add-ins oder Diensten synchronisieren.
Hochladen von Dateien mithilfe der REST-API und jQuery	In den Codebeispielen in diesem Artikel werden die REST-Schnittstelle und jQuery AJAX-Anforderungen verwendet, um eine lokale Datei zur Bibliothek „Documents“ hinzuzufügen und dann die Eigenschaften des Listenelements zu ändern, das die hochgeladene Datei darstellt.
Festlegen von benutzerdefinierten Berechtigungen in einer Liste mit der REST-Schnittstelle	SharePoint-Websites, Listen und Listenelemente sind Typen von SecurableObject, das die Berechtigungen seines übergeordneten Elements erbt. Wenn Sie benutzerdefinierte Berechtigungen für ein Objekt festlegen möchten, müssen Sie die Vererbung der Berechtigungen unterbrechen und dann durch Hinzufügen oder Entfernen von Rollenzuweisungen neue Berechtigungen definieren.
Grundlegendes zu SharePoint-Workflows	Fügen Sie Client- und mobilen Anwendungen mithilfe des Search-REST-Diensts in SharePoint Server 2013 und jeder Technologie, die REST-Webanfragen unterstützt, Suchfunktionen hinzu.
REST-API-Referenz für sozialen Feed für SharePoint	SharePoint-REST-Endpunkte für feedbezogene Aufgaben.
REST-API-Referenz zum Folgen von Personen und Inhalten für SharePoint	SharePoint-REST-Endpunkte zum Folgen von Personen und Inhalten.
Entwickeln von SharePoint-Add-Ins	Hier finden Sie ausführliche Artikel und Ressourcen, die Sie dabei unterstützen, erweiterte Funktionen in Ihre SharePoint-Add-Ins zu integrieren.