Ausführen grundlegender Vorgänge unter Verwendung von SharePoint-REST-Endpunkten

Sie können grundlegende Erstellungs-, Lese-, Aktualisierungs- und Löschoperationen (Create, Read, Update, Delete: CRUD) durchführen, indem Sie die von SharePoint bereitgestellte REST (Representational State Transfer)-Schnittstelle verwenden. Die REST-Schnittstelle macht alle SharePoint-Entitäten und -Vorgänge verfügbar, die in den anderen SharePoint-Client-APIs verfügbar sind. Ein Vorteil bei der Verwendung von REST besteht darin, dass Sie keine Verweise auf SharePoint-Bibliotheken oder Clientassemblys hinzufügen müssen. Stattdessen führen Sie HTTP-Anforderungen an die entsprechenden Endpunkte durch, um SharePoint-Entitäten wie Websites, Listen und Listenelemente abzurufen oder zu aktualisieren.

Eine Einführung in die SharePoint-REST-Schnittstelle und ihre Architektur finden Sie unter Grundlegendes zum SharePoint REST-Dienst.

Informationen zum Arbeiten mit den wichtigsten SharePoint-Entitäten finden Sie unter Arbeiten mit Listen und Listenelementen unter Verwendung von REST und Arbeiten mit Ordnern und Dateien unter Verwendung von REST.

Ein Beispiel, in dem gezeigt wird, wie viele dieser Vorgänge im Kontext einer in C# geschriebenen ASP.NET-Webanwendung ausgeführt werden, finden Sie unter SharePoint-Add-in-REST-OData-BasicDataOperations.

Informationen zu den Gruppen von APIs, die auf der SharePoint-Plattform verfügbar sind, finden Sie unter Auswählen des richtigen API-Satzes in SharePoint.

Informationen zum Verwenden der anderen Client-APOs finden Sie in folgenden Themen:

• Ausführen grundlegender Vorgänge unter Verwendung von JavaScript-Bibliothekscode in SharePoint- Ausführen grundlegender Vorgänge unter Verwendung von SharePoint-Clientbibliothekscode
• Erstellen von Windows Phone-Apps, die auf SharePoint zugreifen

HTTP-Operationen in SharePoint-REST-Diensten

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 (Create, Read, Update und Delete) für SharePoint-Entitäten wie Listen und Websites auszuführen.

In der Regel entsprechen Endpunkte, die Lese-Operationen darstellen, HTTP-GET-Befehlen. Endpunkte, die Erstellungsoperationen darstellen, entsprechen HTTP-POST-Befehlen, und Endpunkte, die Aktualisierungs- oder Einfügeoperationen darstellen, entsprechen HTTP-PUT-Befehlen.

In SharePoint 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 Auflistungen darstellen. Sie können beispielsweise einen POST-Befehl, der eine neue Listenobjektdefinition in ATOM enthält, an die folgende URL senden, um eine SharePoint-Liste zu erstellen:

http://<site url>/_api/web/lists

Alle nicht erforderlichen Eigenschaften in POST-Operationen werden auf ihre Standardwerte festgelegt. Wenn Sie eine schreibgeschützte Eigenschaft im Rahmen einer POST-Operation festzulegen versuchen, gibt der Dienst eine Ausnahme zurück.

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-Anforderungen als auch MERGE-Anforderungen. Bei MERGE-Vorgängen ist das Festlegen von Eigenschaften optional; Eigenschaften, die Sie nicht explizit festlegen, behalten ihre aktuelle Eigenschaft. Bei PUT-Befehlen werden jedoch alle nicht explizit festgelegten Eigenschaften auf ihre Standardeigenschaften festgelegt. Wenn Sie darüber hinaus bei Verwendung von HTTP-PUT-Befehlen nicht alle erforderlichen Eigenschaften in Objektaktualisierungen angeben, gibt der REST-Dienst eine Ausnahme zurück.

Verwenden Sie den HTTP- DELETE-Befehl für die spezifische Endpunkt-URL, um das durch den Endpunkt dargestellte SharePoint-Objekt zu löschen. Bei wiederverwendbaren Objekten, wie Listen, Dateien und Listenelementen, führt dies zu einer Recycle-Operation.

Lesen von Daten mit der SharePoint-REST-Schnittstelle

Um die in SharePoint integrierten REST-Funktionen zu nutzen, erstellen Sie eine RESTful-HTTP-Anforderung mit dem OData-Standard, die der Clientobjektmodell-API entspricht, die Sie verwenden möchten. Jede SharePoint-Entität wird an einem Endpunkt auf der SharePoint-Website verfügbar gemacht, die Sie verwenden möchten, und ihre Metadaten werden entweder im XML- oder JSON-Format dargestellt. Sie können die HTTP-Anforderungen in jeder beliebigen Sprache durchführen, auch in JavaScript und C#.

Um Informationen aus einem REST-Endpunkt zu lesen, müssen Sie die URL des Endpunkts und die OData-Darstellung der SharePoint-Entität kennen, die an diesem Endpunkt verfügbar gemacht wird. Wenn Sie beispielsweise alle Listen auf einer bestimmten SharePoint-Website abrufen möchten, senden Sie eine GET-Anforderung an http://<site url>/_api/web/lists. Sie können zu dieser URL in Ihrem Browser navigieren und das zurückgegebene XML anzeigen. Wenn Sie die Anforderung in Code durchführen, können Sie angeben, ob die OData-Darstellung der Listen im XML- oder JSON-Format erfolgen soll.

Der folgende C#-Code zeigt die Vorgehensweise zum Durchführen der GET-Anforderung, die eine JSON-Darstellung aller Listen einer Website mithilfe von JQuery zurückgibt. Dabei wird auch davon ausgegangen, dass Sie einen gültigen OAuth-Zugriffstoken installiert haben, der in der accessToken-Variablen gespeichert ist. Sie benötigen den Zugriffstoken nicht, wenn Sie den Aufruf, wie bei einem in SharePoint gehosteten Add-In, innerhalb einer Add-In-Website vornehmen. Beachten Sie, dass Sie den Zugriffstoken nicht aus Code abrufen können, der auf einem Browserclient ausgeführt wird. Sie müssen den Zugriffstoken aus Code abrufen, der auf einem Server ausgeführt wird.

Weitere Informationen über das Abrufen eines Zugriffstokens finden Sie unter OAuth-Ablauf mit Kontexttoken für Add-Ins in SharePoint und OAuth-Ablauf mit Authentifizierungscode für SharePoint-Add-Ins

HttpWebRequest endpointRequest =
  (HttpWebRequest)HttpWebRequest.Create(
  "http://<site url>/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization",
  "Bearer " + accessToken);
HttpWebResponse endpointResponse =
  (HttpWebResponse)endpointRequest.GetResponse();

Diese Anforderung würde ein wenig anders aussehen, wenn Sie Ihr Add-In in JavaScript schreiben, während Sie die domänenübergreifende SharePoint-Bibliothek verwenden. In diesem Fall müssen Sie keinen Zugriffstoken zur Verfügung stellen.

Der folgende Code zeigt, wie die Anforderung aussehen würde, wenn Sie die domänenübergreifende Bibliothek verwenden und die OData-Darstellung der Listen im XML-Format anstatt im JSON-Format erfolgen soll. (Da Atom das Standardantwortformat ist, müssen Sie keinen Accept-Header einschließen.) Weitere Informationen zur Verwendung der domänenübergreifenden Bibliothek finden Sie unter Zugreifen auf SharePoint-Daten aus Add-Ins mithilfe der domänenübergreifenden Bibliothek.

var executor = new SP.RequestExecutor(appweburl);
executor.executeAsync(
  {
    url: appweburl +
          "/_api/SP.AppContextSite(@target)/web/lists?@target='" +
          hostweburl + "'",
    method: "GET",
    success: successHandler,
    error: errorHandler
  }
);

Der Code im folgenden Beispiel zeigt, wie Sie eine JSON-Darstellung aller Listen in einer Website anfordern, indem Sie C# verwenden. Es wird davon ausgegangen, dass Sie über ein OAuth-Zugriffstoken verfügen, das Sie in der accessToken Variablen speichern.

HttpWebRequest endpointRequest = (HttpWebRequest)HttpWebRequest.Create(sharepointUrl.ToString() + "/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization", "Bearer " + accessToken);
HttpWebResponse endpointResponse = (HttpWebResponse)endpointRequest.GetResponse();

Abrufen von Eigenschaften, die nicht mit der Ressource zurückgegeben werden

Viele Eigenschaftswerte werden zurückgegeben, wenn Sie eine Ressource abrufen, aber für einige Eigenschaften müssen Sie eine GET-Anforderung direkt an den Eigenschaftenendpunkt senden. Dies ist typisch für Eigenschaften, die SharePoint-Entitäten darstellen.

Das folgende Beispiel zeigt, wie Sie eine Eigenschaft abrufen, indem Sie den Namen der Eigenschaft an den Ressourcenendpunkt anhängen. Im Beispiel wird der Wert der Eigenschaft Author von einer File-Ressource abgerufen.

http://<site url>/_api/web/getfilebyserverrelativeurl('/<folder name>/<file name>')/author

Um die Ergebnisse im JSON-Format zu erhalten, fügen Sie einen Accept-Header zu "application/json;odata=verbose" hinzu.

Schreiben von Daten unter Verwendung der REST-Schnittstelle

Sie können SharePoint-Entitäten erstellen und aktualisieren, indem Sie RESTful-HTTP-Anforderungen an die entsprechenden Endpunkte erstellen, genauso wie beim Lesen von Daten. Ein wesentlicher Unterschied dabei ist jedoch, dass Sie eine POST-Anforderung verwenden. Beim Aktualisieren von Entitäten übergeben Sie außerdem eine PUT- oder MERGE-HTTP-Anforderungsmethode, indem Sie einen dieser Begriffe den Headern Ihrer Anforderung als Wert des X-HTTP-Method-Schlüssels hinzufügen. Die MERGE-Methode aktualisiert nur die Eigenschaften der von Ihnen angegebenen Entität, während die PUT-Methode die bestehende Entität durch eine neue ersetzt, die Sie im Textkörper der POST-Anforderung angeben. Verwenden Sie die DELETE-Methode, um die Entität zu löschen. Beim Erstellen oder Aktualisieren einer Entität müssen Sie eine OData-Darstellung der Entität, die Sie erstellen oder ändern möchten, im Textkörper Ihrer HTTP-Anforderung bereitstellen.

Eine weitere wichtige Überlegung beim Erstellen, Aktualisieren und Löschen von SharePoint-Entitäten ist, dass diese Vorgänge auch den Anforderungsformular-Digestwert des Servers als Wert des X-RequestDigest-Headers erfordern, wenn Sie nicht OAuth verwenden, um Ihre Anforderungen zu autorisieren. Sie können diesen Wert abrufen, indem Sie eine POST-Anforderung mit leerem Textkörper an http://<site url>/_api/contextinfo senden und den Wert des d:FormDigestValue-Knotens aus der XML-Datei extrahieren, das der contextinfo-Endpunkt zurückgibt. Das folgende Beispiel zeigt eine HTTP-Anforderung an den contextinfo-Endpunkt in C#.

HttpWebRequest endpointRequest =(HttpWebRequest)HttpWebRequest.Create(
                                    "http://<site url>/_api/contextinfo");
endpointRequest.Method = "POST";
endpointRequest.Accept = "application/json;odata=verbose";
HttpWebResponse endpointResponse = (HttpWebResponse)endpointRequest.GetResponse();

Wenn Sie den unter Autorisierung und Authentifizierung für SharePoint-Add-Ins beschriebenen Authentifizierungs- und Autorisierungsablauf verwenden, müssen Sie den Anforderungsdigest nicht in Ihre Anforderungen einschließen.

Wenn Sie die domänenübergreifende JavaScript-Bibliothek verwenden, übernimmt SP.RequestExecutor das Abrufen und Senden des Formulardigestwerts für Sie.

Wenn Sie eine in SharePoint gehostete SharePoint-Add-In erstellen, müssen Sie keine separate HTTP-Anforderung durchführen, um den Formulardigestwert abzurufen. Stattdessen können Sie den Wert im JavaScript-Code von der SharePoint-Seite abrufen (wenn die Seite die Standardgestaltungsvorlage verwendet), wie im folgenden Beispiel gezeigt, das JQuery verwendet und eine Liste erstellt.

jQuery.ajax({
        url: "http://<site url>/_api/web/lists",
        type: "POST",
        data:  JSON.stringify({ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true,
 'BaseTemplate': 100, 'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test' }
),
        headers: {
            "accept": "application/json;odata=verbose",
            "content-type": "application/json;odata=verbose",
            "content-length": <length of post body>,
            "X-RequestDigest": $("#__REQUESTDIGEST").val()
        },
        success: doSuccess,
        error: doError
});

Das folgende Beispiel zeigt, wie Sie die im vorherigen Beispiel erstellte Liste aktualisieren. In dem Beispiel wird der Titel der Liste geändert, JQuery wird verwendet, und es wird davon ausgegangen, dass Sie diese Operation in einem in SharePoint gehosteten Add-In durchführen.

jQuery.ajax({
        url: "http://<site url>/_api/web/lists/GetByTitle('Test')",
        type: "POST",
        data: JSON.stringify({ '__metadata': { 'type': 'SP.List' }, 'Title': 'New title' }),
        headers: {
            "X-HTTP-Method":"MERGE",
            "accept": "application/json;odata=verbose",
            "content-type": "application/json;odata=verbose",
            "content-length": <length of post body>,
            "X-RequestDigest": $("#__REQUESTDIGEST").val(),
            "IF-MATCH": "*"
        },
        success: doSuccess,
        error: doError
});

Der Wert des IF-MATCH-Schlüssels in den Anforderungsheadern ist der Ort, an dem Sie den etag-Wert einer Liste oder eines Listenelements angeben. Dieser bestimmte Wert gilt nur für Listen und Listenelemente und soll Ihnen helfen, Parallelitätsprobleme zu vermeiden, wenn Sie diese Entitäten aktualisieren. Im vorherigen Beispiel wird ein Sternchen (*) für diesen Wert verwendet, und Sie können diesen Wert verwenden, wenn Sie keinen Grund haben, sich um Parallelitätsprobleme zu kümmern. Andernfalls sollten Sie den eTag-Wert oder eine Liste oder ein Listenelement abrufen, indem Sie eine GET-Anforderung ausführen, die die Entität abruft. Die Antwortheader der resultierenden HTTP-Antwort übergeben das etag als Wert des ETag-Schlüssels . Dieser Wert ist auch in den Entitätsmetadaten enthalten.

Das folgende Beispiel zeigt das öffnende <entry> Tag für den XML-Knoten, der die Listeninformationen enthält. Die m:etag-Eigenschaft enthält den etag-Wert .

<entry xml:base="http://site url/_api/" xmlns=http://www.w3.org/2005/Atom
       xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
       xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
       xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml" m:etag=""1"">

Erstellen einer Website mit REST

Das folgende Beispiel zeigt, wie Sie eine Website in JavaScript erstellen können.

jQuery.ajax({
    url: "http://<site url>/_api/web/webinfos/add",
    type: "POST",
    data: JSON.stringify(
        {'parameters': {
            '__metadata':  {'type': 'SP.WebInfoCreationInformation' },
            'Url': 'RestSubWeb',
            'Title': 'RestSubWeb',
            'Description': 'REST created web',
            'Language':1033,
            'WebTemplate':'sts',
            'UseUniquePermissions':false}
        }
    ),
    headers: {
        "accept": "application/json; odata=verbose",
        "content-type":"application/json;odata=verbose",
        "content-length": <length of post body>,
        "X-RequestDigest": $("#__REQUESTDIGEST").val()
    },
    success: doSuccess,
    error: doError
});

So unterscheiden sich REST-Anforderungen je nach Umgebung

Der Vorgang zum Erstellen und Senden einer HTTP-Anforderung kann je nach Sprache, Bibliothek und Add-In-Typ variieren, sodass Sie häufig mindestens eine Anforderungskomponente ändern müssen, wenn Sie eine Anforderung aus einer Umgebung in eine andere übertragen. jQuery AJAX-Anforderungen verwenden beispielsweise data- und type-Parameter, um den Anforderungstext und -typ anzugeben, während domänenübergreifende Bibliotheksanforderungen body- und method-Parameter zum Angeben dieser Werte verwenden.

In den folgenden Abschnitten werden weitere allgemeine Unterschiede zwischen Umgebungen beschrieben.

Wie Sie den Formulardigestwert abrufen und senden, hängt von dem Add-In ab

Wenn Sie eine POST-Anforderung senden, muss die Anforderung im X-RequestDigest-Header den Formulardigestwert enthalten. Wie Sie den Wert abrufen und senden, ist jedoch je nach Add-In unterschiedlich:

• In von SharePoint gehosteten Add-Ins können Sie einfach den folgenden Header übergeben:

  "X-RequestDigest": $("#__REQUESTDIGEST").val()

• Rufen Sie in Cloud-gehosteten Add-Ins, die OAuth verwenden, zuerst den Formulardigestwert ab, indem sie eine Anforderung an den contextinfo-Endpunkt senden, und dann der Anforderung den Wert hinzufügen, wie unter Schreiben von Daten unter Verwendung der REST-Schnittstelle gezeigt.

• In in der Cloud gehosteten Add-Ins, die die domänenübergreifende JavaScript-Bibliothek verwenden, müssen Sie den Formulardigestwert nicht angeben. Standardmäßig SP. RequestExecutor übernimmt dies automatisch für Sie. (Es behandelt auch den Wert der Inhaltslänge.)

Add-Ins, die OAuth verwenden, müssen Zugriffstoken in Anforderungen übergeben

In der Cloud gehostete Add-Ins autorisieren den Zugriff auf SharePoint-Daten entweder mit OAuth oder mit der domänenübergreifenden Bibliothek. Add-In-Komponenten mit auf einem Remotewebserver ausgeführtem Code müssen OAuth verwenden, um den Zugriff auf SharePoint-Daten zu autorisieren. In diesem Fall müssen Sie einen Authorization-Header zum Senden des Zugriffstokens einbeziehen. Ein Beispiel, das einem HTTPWebRequest-Objekt einen Autorisierungsheader hinzufügt, finden Sie unter Lesen von Daten mit der SharePoint-REST-Schnittstelle.

Weitere Informationen zu OAuth-Zugriffstoken und wie diese abgerufen werden, finden Sie unter OAuth-Ablauf mit Kontexttoken für Add-Ins in SharePoint und OAuth-Ablauf mit Authentifizierungscode für SharePoint-Add-Ins.

Endpunkt-URIs in domänenübergreifenden Bibliotheksanforderungen verwenden "SP.AppContextSite", um den Kontext zu ändern

Die Anforderungen werden an den in der url-Eigenschaft der Anforderung angegebenen Ressourcenendpunkt gesendet. Endpunkt-URIs verwenden das folgende Format:

<site url>/_api/<context>/<resource> (Beispiel: https://contoso.com/_api/web/lists)

Domänenübergreifende Bibliotheksanforderungen verwenden dieses Format, wenn sie auf Daten im Add-In-Web zugreifen. Dies ist der Standardkontext für domänenübergreifende Bibliotheksanforderungen. Um jedoch auf Daten im Hostweb oder auf eine andere Websitesammlung zuzugreifen, müssen die Anforderungen das Hostweb oder eine andere Websitesammlung als Kontext initialisieren. Dazu verwenden sie den SP. AppContextSite-Endpunkt im URI, wie in Tabelle 1 dargestellt. Die Beispiel-URIs in Tabelle 1 verwenden den @target Alias, um die Ziel-URL in der Abfragezeichenfolge zu senden, da die URL ein Sonderzeichen (":") enthält.

Tabelle 1. Verwenden des SP. AppContextSite-Endpunkt zum Ändern des Kontexts der Anforderung

SharePoint-Add-Ins können die Add-In-Web-URL und die Hostweb-URL aus der Abfragezeichenfolge der Add-In-Seite abrufen, wie im folgenden Codebeispiel dargestellt. In dem Beispiel wird auch gezeigt, wie auf die domänenübergreifende Bibliothek verwiesen wird, die in der Datei „SP.RequestExecutor.js“ im Hostweb definiert ist. In dem Beispiel wird davon ausgegangen, dass das Add-In von SharePoint aus wird gestartet. Eine Anleitung zum richtigen Festlegen des SharePoint-Kontexts, wenn das Add-In nicht aus SharePoint gestartet wird, finden Sie unter OAuth-Fluss für Autorisierungscode für SharePoint-Add-Ins.

var hostweburl;
var appweburl;

// Get the URLs for the add-in web the host web URL from the query string.
$(document).ready(function () {
  //Get the URI decoded URLs.
  hostweburl = decodeURIComponent(getQueryStringParameter("SPHostUrl"));
  appweburl = decodeURIComponent(getQueryStringParameter("SPAppWebUrl"));

  // Load the SP.RequestExecutor.js file.
  $.getScript(hostweburl + "/_layouts/15/SP.RequestExecutor.js", runCrossDomainRequest);
});

// Build and send the HTTP request.
function runCrossDomainRequest() {
  var executor = new SP.RequestExecutor(appweburl);
  executor.executeAsync({
      url: appweburl + "/_api/SP.AppContextSite(@target)/web/lists?@target='" + hostweburl + "'",
      method: "GET",
      headers: { "Accept": "application/json; odata=verbose" },
      success: successHandler,
      error: errorHandler
  });
}

// Get a query string value.
// For production add-ins, you may want to use a library to handle the query string.
function getQueryStringParameter(paramToRetrieve) {
  var params = document.URL.split("?")[1].split("&");
  var strParams = "";
  for (var i = 0; i < params.length; i = i + 1) {
    var singleParam = params[i].split("=");
    if (singleParam[0] == paramToRetrieve) return singleParam[1];
  }
}
??? // success and error callback functions

In REST-Anforderungen verwendete Eigenschaften

In Tabelle 2 werden häufig in HTTP-Anforderungen für den SharePoint-REST-Dienst verwendete Eigenschaften aufgeführt.

Tabelle 2. Verwendung von REST-Anforderungseigenschaften in HTTP-Anforderungen

Unterstützung für Batchaufträge

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.

Siehe auch

• Grundlegendes zum SharePoint-REST-Dienst
• Sicherer Datenzugriff und Clientobjektmodelle für SharePoint-Add-Ins
• Arbeiten mit externen Daten in SharePoint
• OData-Ressourcen
• Festlegen von benutzerdefinierten Berechtigungen in einer Liste mit der REST-Schnittstelle
• Entwickeln von SharePoint-Add-ins