Ermitteln von URIs von SharePoint-REST-Dienstendpunkten
Tipp
Bevor Sie beginnen, überprüfen Sie die folgenden Ressourcen:
Grundlegendes zum SharePoint-REST-DienstNavigieren in der im REST-Dienst dargestellten SharePoint-Datenstruktur
Struktur der URIs von SharePoint-REST-Endpunkten
Bevor Sie mithilfe des REST-Diensts auf eine SharePoint-Ressource zugreifen können, müssen Sie zuerst den URI-Endpunkt ermitteln, der auf diese Ressource zeigt. Wann immer möglich, bildet die URI für diese REST-Endpunkte die API-Signatur der Ressource im SharePoint-Clientobjektmodell streng nach. Zum Beispiel:
In einigen Fällen unterscheidet sich die Endpunkt-URI aber von der entsprechenden Clientobjektmodell-Signatur, um REST- oder OData-Konventionen zu erfüllen.
Die folgende Abbildung zeigt die allgemeine Syntaxstruktur von SharePoint REST-URIs.
Syntaxstruktur von SharePoint REST-URIs**
Einige Endpunkte für SharePoint-Ressourcen weichen von dieser Syntaxstruktur ab:
- Methoden, die komplexe Typen als Parameter erfordern. Wenn die entsprechende Clientobjektmodell-Methode erfordert, dass komplexe Typen als Parameter übergeben werden, kann der REST-Endpunkt wegen REST-Einschränkungen von dieser Syntaxstruktur abweichen.
- Statische Methoden und Eigenschaften. REST-Endpunkte weichen von dieser Syntaxstruktur bei URIs ab, die statische Methoden und Eigenschaften darstellen.
Ermitteln von SharePoint-REST-Dienstendpunkten
Befolgen Sie diese Schritte, um einen REST-Endpunkt für eine SharePoint-Ressource zu erstellen:
Starten Sie mit der REST-Dienstreferenz:
https://{site_url}/_apiGeben Sie den entsprechenden Einstiegspunkt an. Beispiel:
https://{site_url}/_api/webNavigieren Sie vom Einstiegspunkt zu den spezifischen Ressourcen, auf die Sie zugreifen möchten. Dabei müssen Sie auch Parameter für Endpunkte angeben, die Methoden im Clientobjektmodell entsprechen. Beispiel:
https://{site_url}/_api/web/lists/getbytitle('{list_name}')
Referenzieren Sie den SharePoint REST-Dienst in Ihrem Endpunkt-URI
Verwenden Sie _api, um den SharePoint REST-Dienst in Ihren Endpunkt-URIs zu kennzeichnen. Der REST-Dienst ist Teil des Webdiensts „client.svc“. Um die Erstellung von REST-URIs zu erleichtern und den REST URI-Basispfad zu kürzen, verwendet der REST-Dienst _api, wodurch der explizite Verweis auf den Webdienst „client.svc“ nicht mehr erforderlich ist.
URIs, die auf den Webdienst „client.svc“ verweisen, werden vom REST-Dienst jedoch weiterhin erkannt und akzeptiert. Sie können z. B. https://{site_url}/_vti_bin/client.svc/web/lists anstelle von https://{site_url}/_api/web/lists verwenden. Allerdings ist _api die bevorzugte Konvention. URLs haben maximal 256 Zeichen. Mit _api wird der Basis-URI verkürzt und es bleiben mehr Zeichen für die Erstellung der verbleibenden URL übrig.
Angeben von Einstiegspunkten für den SharePoint REST-Dienst
Die wichtigsten Einstiegspunkte für den REST-Dienst sind die Websitesammlung und die Website des angegebenen Kontexts. Damit entsprechen diese Einstiegspunkte den Eigenschaften ClientContext.Site und ClientContext.Web in den Clientobjektmodellen.
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
Zusätzlich zu /site und /web enthält der REST-Dienst mehrere Zugriffspunkte, die Entwicklern erlauben, zu spezifischen Funktionen zu navigieren. In der folgenden Tabelle sind einige dieser Zugriffspunkte aufgeführt.
| Funktionsbereich | Zugriffspunkt |
|---|---|
| Website | https://{site_url}/_api/site |
| Web | https://{site_url}/_api/web |
| Benutzerprofil | https://{site_url}/_api/SP.UserProfiles.PeopleManager |
| Suche | https://{site_url}/_api/search |
Navigieren zu den Ressourcen, auf die Sie zugreifen möchten
Erstellen Sie hier mithilfe des Objektmodells spezifischere REST-Endpunkte mit den Namen der APIs aus dem Clientobjektmodell, jeweils getrennt durch einen Schrägstrich (/). In der Tabelle unten sehen Sie Beispiele für Clientobjektmodell-Aufrufe und die zugehörigen REST-Endpunkte.
| Clientobjektmodell-API | REST-Endpunkt |
|---|---|
| ClientContext.Web.Lists | https://{site_url}/_api/web/lists |
| ClientContext.Web.Lists[guid] | https://{site_url}/_api/web/lists('<guid>') |
| ClientContext.Web.Lists.GetByTitle("Title") | https://{site_url}/_api/web/lists/getbytitle('<Title>') |
Bei Endpunkt-URIs wird die Groß- und Kleinschreibung nicht beachtet. Verwenden Sie in der vorhergehenden Tabelle z. B. /getbytitle, um das REST-Äquivalent der GetByTitle()-Methode anzugeben.
Angeben von Parametern in REST-Endpunkt-URIs
SharePoint erweitert die OData-Spezifikation, um es Ihnen zu ermöglichen, für die Angabe von Methodenparametern und Indexwerten Klammern zu verwenden. Dadurch werden Fehler durch Mehrdeutigkeiten in URIs vermieden, die mehrere Parameter mit dem gleichen Namen enthalten. Die folgenden beiden URIs enthalten beispielsweise Parameter, die den gleichen Namen aufweisen:
https://{site_url}/_api/web/lists/getByTitle('Announcements')/fields/getByTitle('Description')
https://{site_url}/_api/web/lists('{list_guid}')/fields/getById('{guid}')
Um mehrere Parameter anzugeben, schließen Sie den Parameter als ein Namen-Wert-Paar ein, und trennen Sie die Parameter mit Kommas. Beispiel:
https://{site_url}/_api/web/getAvailableWebTemplates(lcid=1033, includeCrossLanguage=true)
Die folgende Abbildung zeigt die Syntax von SharePoint-REST-Parametern.
Syntax von SharePoint REST-Parametern
Komplexe Typen als Parameter für den REST-Dienst
Einige Methoden im Clientobjektmodell erfordern eine große Nutzlast als Parameter. Damit REST-Endpunkte die Funktionsparität mit ihren entsprechenden Clientobjektmodell-APIs aufrechterhalten, müssen die Endpunkte einen komplexen Typ als Parameter akzeptieren. In diesen Fällen erweitert der REST-Dienst das bestehende OData-Protokoll, damit diese REST-Endpunkte einen einzelnen komplexen Typ als Parameter akzeptieren können. Dies bezieht sich nur auf POST-Vorgänge, und Sie müssen den komplexen Typ gemäß OData-Standards in Atom-Format oder JSON-Format übergeben.
So verwendet beispielsweise die Methode ListCollection.Add ein Microsoft.SharePoint.Client.ListCreationInformation-Objekt als Parameter. Um eine Liste zu einer bestimmten Website hinzuzufügen, erstellen Sie den entsprechenden REST-Endpunkt wie folgt:
POST https://{site_url}/_api/web/lists/add
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
{ "d" : {
"results": {
"__metadata": {
"type": "SP.ListCreationInformation"
},
"CustomSchemaXml": "…large payload…/",
"Description": "desc",
"DocumentTemplateType": "1",
"TemplateType": "101",
"Title": "Announcements"
}
}
}
Verwenden von Parameter-Aliasen in REST-Dienstaufrufen
Sie können die "Parameteraliasing"-Semantik in OData verwenden, um Parameter an einen SharePoint-REST-Endpunkt zu übergeben. Beim Parameteraliasing wird der Parameterwert mit einem Alias im Parameteraufruf identifiziert, und der tatsächliche Wert wird in der Abfragezeichenfolge der URI angegeben. So können Sie mehr Zeichentypen und eine einheitliche Formatierung mithilfe der Abfragezeichenfolge unterstützen.
Die folgenden zwei REST-URIs sind z. B. äquivalent:
Geben Sie den Parameterwert direkt an:
https://{site_url}/_api/web/applyWebTemplate("STS#0")
Verwenden Sie einen Parameteralias, und geben Sie den tatsächlichen Parameterwert in der Abfragezeichenfolge der URI an:
https://{site_url}/_api/web/applyWebTemplate(title=@template)?@template="STS#0"
Das Übergeben von komplexen Typen per Parameteraliasing wird vom SharePoint-REST-Dienst allerdings nicht unterstützt. So wird z. B. die folgende URI nicht unterstützt, die einen komplexen Typ im Parameteralias enthält:
https://{site_url}/_api/userProfiles/People(7)/GetWorkplace(@address)?@address={"__metadata":{"type: "ODataDemo.Address"},"Street":"NE 228th", "City":"Sammamish","State":"WA","ZipCode":"98074","Country": "USA"}
Parameter-Aliasing-Syntax des SharePoint REST-Diensts
Angeben von Schlüsselverzeichnissen als Parameterwerte
Bei REST-Endpunkten, die Methoden entsprechen, die Dictionary<String, String>-Wörterbücher als Parameter verwenden, übergeben Sie das Wörterbuch als Serie von durch Kommas getrennten Namen-Wert-Paaren in der Abfragezeichenfolge.
REST-Dienstsyntax für Wörterbuchparameter
Ein Objekt des Typs Dictionary<String, object> wird als Mehrfachwertobjekt namens „KeyedPropertyValue“ mit den folgenden Zeichenfolgeneigenschaften dargestellt:
- Key Der Schlüssel des Mehrfachwertobjekts.
- Value Der Wert des Objekts
- Valuetype Der Werttyp des Objekts. Für einfache Werttypen, die vorhandenen EDM-Typen (Entity Data Model) zugeordnet sind, gibt der REST-Dienst die entsprechende EDM-Typzeichenfolge zurück. Beispiel: "Edm.String". Andernfalls gibt der REST-Dienst den von der Type.ToString-Funktion zurückgegebenen Werttyp zurück.
Angeben von Parameterwerten in der Abfragezeichenfolge
Wenn Ihre REST-URI in einem Methodenaufruf endet, können Sie Abfragezeichenfolgensyntax verwenden, um die Parameterwerte der Methode anzugeben. Beispiel:
https://{site_url}/_api/web/applyWebTemplate?template="STS#0"
In der folgenden Abbildung wird die Syntax veranschaulicht, die der REST-Dienst für Parameter in einer Abfragezeichenfolge verwendet.
REST-Dienstsyntax für Parameter in Abfragezeichenfolgen
Angeben von statischen Methoden und Eigenschaften als REST-Dienst-URIs
Um URIs zu erstellen, die statischen Methoden oder Eigenschaften entsprechen, verwenden Sie den entsprechenden API-Namen aus dem ECMAScript-Objektmodell, beginnend mit der Namespacedeklaration und unter Verwendung von punktierter Schreibweise. Beispiel: SP. Utilities.Utility.getImageUrl(imageName) im ECMAScript-Clientobjektmodell hätte das folgende REST-Äquivalent:
https://{site_url}/_api/SP.Utilities.Utility.getImageUrl('imageName')
Statische Methoden können allerdings nur direkt aufgerufen werden und sind als Teil einer größeren URI-Komposition nicht zulässig. Das direkte Aufrufen der SP.Utility.AssetsLibrary-Methode in REST ist z. B. wie folgt zulässig:
https://{site_url}/_api/SP.Utility.assetsLibrary/id
Die Verwendung des Ressourcenspeicherorts als Parameter für eine komplexere URI, wie im folgenden Beispiel gezeigt, ist allerdings nicht zulässig:
https://{site_url}/_api/getList(~SP.Utility/assetsLibrary/id)
In der folgenden Abbildung wird die Syntax veranschaulicht, die der SharePoint-REST-Dienst für statische Elemente verwendet.
Syntax von statischen Membern des SharePoint REST-Diensts
Wenn Sie die von einem Endpunkt angeforderten Daten auswählen, filtern oder sortieren möchten, unterstützt der SharePoint-REST-Dienst eine breite Palette von OData-Abfragezeichenfolgen-Operatoren. Weitere Informationen finden Sie unter Verwenden von OData-Abfragevorgängen in SharePoint REST-Anforderungen