Ausführen grundlegender Vorgänge unter Verwendung von SharePoint-REST-EndpunktenComplete basic operations using SharePoint REST endpoints

You can perform basic create, read, update, and delete (CRUD) operations by using the Representational State Transfer (REST) interface provided by SharePoint. The REST interface exposes all the SharePoint entities and operations that are available in the other SharePoint client APIs. One advantage of using REST is that you don't have to add references to any SharePoint libraries or client assemblies. Instead, you make HTTP requests to the appropriate endpoints to retrieve or update SharePoint entities, such as webs, lists, and list items.You can perform basic create, read, update, and delete (CRUD) operations by using the Representational State Transfer (REST) interface provided by SharePoint. The REST interface exposes all the SharePoint entities and operations that are available in the other SharePoint client APIs. One advantage of using REST is that you don't have to add references to any SharePoint libraries or client assemblies. Instead, you make HTTP requests to the appropriate endpoints to retrieve or update SharePoint entities, such as webs, lists, and list items.

Eine Einführung in die SharePoint-REST-Schnittstelle und ihre Architektur finden Sie unter Grundlegendes zum SharePoint REST-Dienst.For an introduction to the SharePoint REST interface and its architecture, see Get to know the SharePoint REST service.

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.For information about how to work with core SharePoint entities, see Working with lists and list items with REST and Working with folders and files with 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.For a sample that shows you how to do many of these operations in the context of an ASP.NET web application written in C#, see 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.For information about the sets of APIs available on the SharePoint platform, see Choose the right API set in SharePoint.

Informationen zum Verwenden der anderen Client-APOs finden Sie in folgenden Themen:For information about how to use the other client APIs, see:

HTTP-Operationen in SharePoint-REST-DienstenHTTP operations in SharePoint REST services

The endpoints in the SharePoint REST service correspond to the types and members in the SharePoint client object models. By using HTTP requests, you can use these REST endpoints to perform typical CRUD (Create, Read, Update, and Delete) operations against SharePoint entities, such as lists and sites.The endpoints in the SharePoint REST service correspond to the types and members in the SharePoint client object models. By using HTTP requests, you can use these REST endpoints to perform typical CRUD (Create, Read, Update, and Delete) operations against SharePoint entities, such as lists and sites.

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.Typically, endpoints that represent Read operations map to HTTP GET commands, endpoints that represent create operations map to HTTP POST commands, and endpoints that represent update or insert operations map to HTTP PUT commands.

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:In SharePoint, use POST to create entities such as lists and sites. The SharePoint REST service supports sending POST commands that include object definitions to endpoints that represent collections. For example, you could send a POST command that included a new list object definition in ATOM to the following URL, to create a SharePoint list:

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.For POST operations, any properties that are not required are set to their default values. If you attempt to set a read-only property as part of a POST operation, the service returns an exception.

Verwenden Sie die Operationen PUT und MERGE, um vorhandene SharePoint-Objekte zu aktualisieren. Jeder Dienstendpunkt, der eine set-Operation für eine Objekteigenschaft darstellt, unterstützt PUT-Anforderungen und MERGE-Anforderungen. Bei MERGE-Anforderungen ist das Festlegen von Eigenschaften optional. Alle Eigenschaften, die Sie nicht explizit festlegen, behalten ihre aktuelle Eigenschaft. Bei PUT-Befehlen werden jedoch alle Eigenschaften, die Sie nicht explizit festlegen, auf ihre Standardeigenschaften festgelegt. Darüber hinaus gibt der REST-Dienst eine Ausnahme zurück, wenn Sie bei Verwendung von HTTP- PUT-Befehlen nicht alle erforderlichen Eigenschaften in Objektaktualisierungen angeben.Use PUT and MERGE operations to update existing SharePoint objects. Any service endpoint that represents an object property set operation supports both PUT requests and MERGE requests. For MERGE requests, setting properties is optional; any properties that you do not explicitly set retain their current property. For PUT commands, however, any properties you do not explicitly set are set to their default properties. In addition, if you do not specify all required properties in object updates when using HTTP PUT commands, the REST service returns an exception.

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.Use the HTTP DELETE command against the specific endpoint URL to delete the SharePoint object represented by that endpoint. In the case of recyclable objects, such as lists, files, and list items, this results in a Recycle operation.

Lesen von Daten mit der SharePoint-REST-SchnittstelleReading data with the SharePoint REST interface

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#.To use the REST capabilities that are built into SharePoint, you construct a RESTful HTTP request, using the OData standard, which corresponds to the client object model API you want to use. Each SharePoint entity is exposed at an endpoint on the SharePoint site that you are targeting, and its metadata is represented in either XML or JSON format. You can make the HTTP requests in any language, including but not limited to JavaScript and C#.

To read information from a REST endpoint, you must know both the URL of the endpoint and the OData representation of the SharePoint entity that is exposed at that endpoint. For example, to retrieve all the lists in a specific SharePoint site, you would make a GET request to http://<site url>/_api/web/lists. You can navigate to this URL in your browser and see the XML that gets returned. When you make the request in code, you can specify whether to receive the OData representation of the lists in XML or JSON.To read information from a REST endpoint, you must know both the URL of the endpoint and the OData representation of the SharePoint entity that is exposed at that endpoint. For example, to retrieve all the lists in a specific SharePoint site, you would make a GET request to http://<site url>/_api/web/lists. You can navigate to this URL in your browser and see the XML that gets returned. When you make the request in code, you can specify whether to receive the OData representation of the lists in XML or JSON.

The following C# code demonstrates how to make this GET request that returns a JSON representation of all of a site's lists by using JQuery. It also assumes that you have a valid OAuth access token that is stored in the accessToken variable. You do not need the access token if you make this call from inside an add-in web, as you would in a SharePoint-hosted add-in. Note that you cannot obtain an access token from code that is running on a browser client. You must obtain the access token from code that is running on a server.The following C# code demonstrates how to make this GET request that returns a JSON representation of all of a site's lists by using JQuery. It also assumes that you have a valid OAuth access token that is stored in the accessToken variable. You do not need the access token if you make this call from inside an add-in web, as you would in a SharePoint-hosted add-in. Note that you cannot obtain an access token from code that is running on a browser client. You must obtain the access token from code that is running on a server.

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-InsFor more information about how you can obtain an access token, see Context Token OAuth flow for SharePoint Add-ins and Authorization Code OAuth flow for 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();

This request would look a little different if you are writing your add-in in JavaScript while using the SharePoint cross-domain library. In this case, you don't need to provide an access token.This request would look a little different if you are writing your add-in in JavaScript while using the SharePoint cross-domain library. In this case, you don't need to provide an access token.

The following code demonstrates how this request would look if you are using the cross-domain library and want to receive the OData representation of the lists as XML instead of JSON. (Because Atom is the default response format, you don't have to include an Accept header.) For more information about using the cross-domain library, see Access SharePoint data from add-ins using the cross-domain library.The following code demonstrates how this request would look if you are using the cross-domain library and want to receive the OData representation of the lists as XML instead of JSON. (Because Atom is the default response format, you don't have to include an Accept header.) For more information about using the cross-domain library, see Access SharePoint data from add-ins using the cross-domain library.

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. Das Beispiel geht davon aus, dass Sie über einen OAuth-Zugriffstoken verfügen, den Sie in der accessToken-Variablen speichern.The code in the following example shows you how to request a JSON representation of all of the lists in a site by using C#. It assumes that you have an OAuth access token that you are storing in the accessToken variable.

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 werdenGetting properties that aren't returned with the resource

Viele Eigenschaftswerte werden zurückgegeben, wenn Sie eine Ressource abrufen. Bei einigen Eigenschaften müssen Sie allerdings eine GET-Anforderung direkt an den Eigenschaftsendpunkt senden. Dies gilt i. d. R. für Eigenschaften, die SharePoint-Entitäten darstellen.Many property values are returned when you retrieve a resource, but for some properties, you have to send a GET request directly to the property endpoint. This is typical of properties that represent SharePoint entities.

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.The following example shows how to get a property by appending the property name to the resource endpoint. The example gets the value of the Author property from a File resource.

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.To get the results in JSON format, include an Accept header set to "application/json;odata=verbose".

Schreiben von Daten unter Verwendung der REST-SchnittstelleWriting data by using the REST interface

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.You can create and update SharePoint entities by constructing RESTful HTTP requests to the appropriate endpoints, just as you do when you're reading data. One key difference, however, is that you use a POST request. When you're updating entities, you also pass a PUT or MERGE HTTP request method by adding one of those terms to the headers of your request as the value of the X-HTTP-Method key. The MERGE method updates only the properties of the entity that you specify, while the PUT method replaces the existing entity with a new one that you supply in the body of the POST. Use the DELETE method to delete the entity. When you create or update an entity, you must provide an OData representation of the entity that you want to create or change in the body of your HTTP request.

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#.Another important consideration when creating, updating, and deleting SharePoint entities is that if you aren't using OAuth to authorize your requests, these operations require the server's request form digest value as the value of the X-RequestDigest header. You can retrieve this value by making a POST request with an empty body to http://<site url>/_api/contextinfo and extracting the value of the d:FormDigestValue node in the XML that the contextinfo endpoint returns. The following example shows an HTTP request to the contextinfo endpoint 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.If you're using the authentication and authorization flow described in Authorization and authentication of SharePoint Add-ins, you don't need to include the request digest in your requests.

Wenn Sie die domänenübergreifende JavaScript-Bibliothek verwenden, übernimmt SP.RequestExecutor das Abrufen und Senden des Formulardigestwerts für Sie.If you're using the JavaScript cross-domain library, SP.RequestExecutor handles getting and sending the form digest value for you.

If you're creating a SharePoint-hosted SharePoint Add-in, you don't have to make a separate HTTP request to retrieve the form digest value. Instead, you can retrieve the value in JavaScript code from the SharePoint page (if the page uses the default master page), as shown in the following example, which uses JQuery and creates a list.If you're creating a SharePoint-hosted SharePoint Add-in, you don't have to make a separate HTTP request to retrieve the form digest value. Instead, you can retrieve the value in JavaScript code from the SharePoint page (if the page uses the default master page), as shown in the following example, which uses JQuery and creates a list.

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.The following example shows how to update the list that is created in the previous example. The example changes the title of the list, uses JQuery, and assumes that you are doing this operation in a SharePoint-hosted add-in.

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

The value of the IF-MATCH key in the request headers is where you specify the etag value of a list or list item. This particular value applies only to lists and list items, and is intended to help you avoid concurrency problems when you update those entities. The previous example uses an asterisk (*) for this value, and you can use that value whenever you don't have any reason to worry about concurrency issues. Otherwise, you should obtain the etag value or a list or list item by performing a GET request that retrieves the entity. The response headers of the resulting HTTP response pass the etag as the value of the ETag key. This value is also included in the entity metadata.The value of the IF-MATCH key in the request headers is where you specify the etag value of a list or list item. This particular value applies only to lists and list items, and is intended to help you avoid concurrency problems when you update those entities. The previous example uses an asterisk (*) for this value, and you can use that value whenever you don't have any reason to worry about concurrency issues. Otherwise, you should obtain the etag value or a list or list item by performing a GET request that retrieves the entity. The response headers of the resulting HTTP response pass the etag as the value of the ETag key. This value is also included in the entity metadata.

The following example shows the opening <entry> tag for the XML node that contains the list information. The m:etag property contains the etag value.The following example shows the opening <entry> tag for the XML node that contains the list information. The m:etag property contains the etag value.

<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 RESTCreating a site with REST

Das folgende Beispiel zeigt, wie Sie eine Website in JavaScript erstellen können.The following example shows how to create a site in JavaScript.

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

Hinweis

Setting WebTemplate to 'sts' will create a modern homepage. To create a classic homepage, set WebTemplate to 'sts#0'.Setting WebTemplate to 'sts' will create a modern homepage. To create a classic homepage, set WebTemplate to 'sts#0'.

So unterscheiden sich REST-Anforderungen je nach UmgebungHow REST requests differ by environment

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.Building and sending an HTTP request may vary according to language, library, and add-in type, so you often need to change one or more request components when you're translating a request from one environment to another. For example, jQuery AJAX requests use data and type parameters to specify the request body and type, but cross-domain library requests use body and method parameters to specify those values.

In den folgenden Abschnitten werden weitere allgemeine Unterschiede zwischen Umgebungen beschrieben.The following sections describe other common differences across environments.

Wie Sie den Formulardigestwert abrufen und senden, hängt von dem Add-In abThe way you get and send the form digest value depends on the add-in

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:When you send a POST request, the request must include the form digest value in the X-RequestDigest header. However, the way you get and send the value differs by add-in:

  • In von SharePoint gehosteten Add-Ins können Sie einfach den folgenden Header übergeben:In SharePoint-hosted add-ins, you can just pass the following header:

    "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 cloud-hosted add-ins that use OAuth, first retrieve the form digest value by sending a request to the contextinfo endpoint, and then add it to requests, as shown in Writing data by using the REST interface.

  • In Cloud-gehosteten Add-Ins, welche die domänenübergreifende JavaScript-Bibliothek verwenden, müssen Sie den Formulardigestwert nicht angeben. SP.RequestExecutor gibt diesen automatisch für Sie an (ebenso wie den Inhalt-Länge-Wert).In cloud-hosted add-ins that use the JavaScript cross-domain library, you don't need to specify the form digest value. By default, SP.RequestExecutor automatically handles this for you. (It also handles the content-length value.)

Add-Ins, die OAuth verwenden, müssen Zugriffstoken in Anforderungen übergebenAdd-ins that use OAuth must pass access tokens in requests

Cloud-hosted add-ins use either OAuth or the cross-domain library to authorize access to SharePoint data. Add-in components with code that runs on a remote web server must use OAuth to authorize access to SharePoint data. In this case, you need to include an Authorization header to send the access token. For an example that adds an authorization header to an HTTPWebRequest object, see Reading data with the SharePoint REST interface.Cloud-hosted add-ins use either OAuth or the cross-domain library to authorize access to SharePoint data. Add-in components with code that runs on a remote web server must use OAuth to authorize access to SharePoint data. In this case, you need to include an Authorization header to send the access token. For an example that adds an authorization header to an HTTPWebRequest object, see Reading data with the SharePoint REST interface.

Hinweis

Cloud-hosted add-in components that are written in JavaScript must use the SP.RequestExecutor object in the cross-domain library to access to SharePoint data. Cross-domain library requests don't need to include an access token.Cloud-hosted add-in components that are written in JavaScript must use the SP.RequestExecutor object in the cross-domain library to access to SharePoint data. Cross-domain library requests don't need to include an access token.

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.To learn more about OAuth access tokens and how to get them, see Context Token OAuth flow for SharePoint Add-ins and Authorization Code OAuth flow for SharePoint Add-ins.

Endpunkt-URIs in domänenübergreifenden Bibliotheksanforderungen verwenden "SP.AppContextSite", um den Kontext zu ändernEndpoint URIs in cross-domain requests use SP.AppContextSite to change the context

Die Anforderungen werden an den in der url-Eigenschaft der Anforderung angegebenen Ressourcenendpunkt gesendet. Endpunkt-URIs verwenden das folgende Format:Requests are sent to the resource endpoint that's specified in the url property of the request. Endpoint URIs use the following format:

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

Domänenübergreifende Bibliotheksanforderungen verwenden dieses Format für den Zugriff auf Daten im Add-In-Web. Dies ist der Standardkontext für domänenübergreifende Bibliotheksanforderungen. Um jedoch auf Daten im Hostweb oder in einer anderen Websitesammlung zugreifen zu können, müssen die Anforderungen das Hostweb oder die andere Websitesammlung als Kontext initialisieren. Hierzu wird wie in Tabelle 1 gezeigt der SP.AppContextSite-Endpunkt im URI verwendet. Die in Tabelle 1 aufgeführten Beispiel-URIs verwenden den @target-Alias zum Senden der Ziel-URL in der Abfragezeichenfolge, weil die URL ein Sonderzeichen (':') enthält.Cross-domain library requests use this format when they access data on the add-in web, which is the default context for cross-domain library requests. But to access data on the host web or on another site collection, the requests need to initialize the host web or other site collection as the context. To do this, they use the SP.AppContextSite endpoint in the URI, as shown in Table 1. The example URIs in Table 1 use the @target alias to send the target URL in the query string because the URL contains a special character (':').

Hinweis

Damit ein in der Cloud gehostetes Add-In beim Verwenden der domänenübergreifenden Bibliothek auf SharePoint-Daten zugreifen kann, ist eine Add-In-Webinstanz erforderlich.An add-in web instance is required for a cloud-hosted add-in to access SharePoint data when using the cross-domain library.

Tabelle 1: Verwenden des „SP.AppContextSite“-Endpunkts zum Ändern des Kontexts der AnforderungTable 1. Using the SP.AppContextSite endpoint to change the context of the request

Add-In-TypAdd-in type Szenario für den domänenübergreifenden DatenzugriffCross-domain data access scenario Beispiel-Endpunkt-URIExample endpoint URI
In der Cloud gehostetCloud-hosted JavaScript-Add-In-Komponente, die mithilfe der domänenübergreifenden Bibliothek auf Hostwebdaten zugreiftJavaScript add-in component accessing host web data by using the cross-domain library <app web url>/_api/SP.AppContextSite(@target)/web/lists?@target='<host web url>'
In der Cloud gehostetCloud-hosted JavaScript-Add-In-Komponente, die mithilfe der domänenübergreifenden Bibliothek auf Daten zugreift, die sich in einer anderen Websitesammlung als dem Hostweb befinden (gilt nur für Add-Ins mit Mandantenbereich)JavaScript add-in component accessing data in a site collection other than the host web by using the cross-domain library (tenant-scoped add-ins only) <app web url>/_api/SP.AppContextSite(@target)/web/title?@target='<target site url>'
Von SharePoint gehostetSharePoint-hosted Add-In-Webkomponente, die auf Daten in einer anderen Websitesammlung zugreift (gilt nur für Add-Ins mit Mandantenbereich)Add-in web component accessing data in another site collection (tenant-scoped add-ins only) <app web url>/_api/SP.AppContextSite(@target)/web/title?@target='<target site url>'

Hinweis

In Szenarien für den domänenübergreifenden Datenzugriff sind auch die entsprechenden Add-In-Berechtigungen erforderlich. Weitere Informationen finden Sie unter Zugreifen auf Daten in einem Hostweb und Zugreifen auf Daten in allen Websitesammlungen.Cross-domain data access scenarios also require appropriate add-in permissions. For more information, see Access data from the host web and Access data across site collections.

SharePoint Add-ins can get the add-in web URL and host web URL from the query string of the add-in page, as shown in the following code example. The example also shows how to reference the cross-domain library, which is defined in the SP.RequestExecutor.js file on the host web. The example assumes that your add-in launches from SharePoint. For guidance about setting your SharePoint context correctly when your add-in does not launch from SharePoint, see Authorization Code OAuth flow for SharePoint Add-ins.SharePoint Add-ins can get the add-in web URL and host web URL from the query string of the add-in page, as shown in the following code example. The example also shows how to reference the cross-domain library, which is defined in the SP.RequestExecutor.js file on the host web. The example assumes that your add-in launches from SharePoint. For guidance about setting your SharePoint context correctly when your add-in does not launch from SharePoint, see Authorization Code OAuth flow for 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("&amp;");
  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 EigenschaftenProperties used in REST requests

In Tabelle 2 werden häufig in HTTP-Anforderungen für den SharePoint-REST-Dienst verwendete Eigenschaften aufgeführt.Table 2 shows properties that are commonly used in HTTP requests for the SharePoint REST service.

Tabelle 2: Verwendung von REST-Anforderungseigenschaften in HTTP-AnforderungenTable 2. When to use REST request properties in HTTP requests

EigenschaftenProperties Wann erforderlichWhen required BeschreibungDescription
urlurl Alle AnforderungenAll requests Die URL eines REST-Ressourcenendpunkts. Beispiel: http://<site url>/_api/web/listsThe URL of the REST resource endpoint. Example: http://<site url>/_api/web/lists
method (oder type)method (or type) Alle AnforderungenAll requests Die HTTP-Anforderungsmethode: GET für Lesevorgänge und POST für Schreibvorgänge. POST-Anforderungen können Aktualisierungs- oder Löschvorgänge durchführen, wenn das Verb DELETE, MERGE oder PUT im X-HTTP-Method-Header angegeben wird. The HTTP request method: GET for read operations and POST for write operations. POST requests can perform update or delete operations by specifying a DELETE, MERGE, or PUT verb in the X-HTTP-Method header.
body (oder data)body (or data) POST-Anforderungen, die Daten im Anforderungstextkörper sendenPOST requests that send data in the request body Der Textkörper der POST-Anforderung. Sendet Daten (z. B. komplexe Typen), die nicht in einer Endpunkt-URI gesendet werden können. Wird mit dem content-length-Header verwendet.The body of the POST request. Sends data (such as complex types) that can't be sent in the endpoint URI. Used with the content-length header.
Authentication-HeaderAuthentication header Remote-Add-Ins, die OAuth verwenden, um Benutzer zu authentifizieren. Gilt nicht bei Verwendung von JavaScript oder der domänenübergreifenden Bibliothek.Remote add-ins that are using OAuth to authenticate users; does not apply when using JavaScript or the cross domain library Sendet den OAuth-Zugriffstoken (erhalten von einem sicheren Token-Server von Microsoft Access Control Service (ACS)), der zur Authentifizierung der Anforderung des Nutzers verwendet wird. Beispiel: "Authorization": "Bearer " + accessToken, wobei accessToken für die Variable steht, die den Token enthält. Token müssen mittels serverseitigem Code abgerufen werden. Sends the OAuth access token (obtained from a Microsoft Access Control Service (ACS) secure token server) that's used to authenticate the user for the request. Example: "Authorization": "Bearer " + accessToken, where accessToken represents the variable that stores the token. Tokens must be retrieved by using server-side code.
X-RequestDigest-HeaderX-RequestDigest header POST-Anforderungen (außer SP.RequestExecutor-Anforderungen)POST requests (except SP.RequestExecutor requests) Remote-Add-Ins, die OAuth verwenden, können den Formulardigestwert vom Endpunkt http://<site url>/_api/contextinfo abrufen. In SharePoint gehostete Add-Ins können den Wert über das #__REQUESTDIGEST-Seitensteuerelement abrufen, wenn es auf der SharePoint-Seite verfügbar ist. Weitere Informationen finden Sie unter Schreiben von Daten unter Verwendung der REST-Schnittstelle. Remote add-ins that use OAuth can get the form digest value from the http://<site url>/_api/contextinfo endpoint. SharePoint-hosted add-ins can get the value from the #__REQUESTDIGEST page control if it's available on the SharePoint page. See Writing data by using the REST interface.
accept-Headeraccept header Anforderungen, die SharePoint-Metadaten zurückgebenRequests that return SharePoint metadata Gibt das Format für Antwortdaten vom Server an. Das Standardformat ist application/atom+xml. Beispiel: "accept":"application/json;odata=verbose"Specifies the format for response data from the server. The default format is application/atom+xml. Example: "accept":"application/json;odata=verbose"
content-type-Headercontent-type header POST-Anforderungen, die Daten im Anforderungstextkörper sendenPOST requests that send data in the request body Gibt das Format der Daten an, die der Client an den Server sendet. Das Standardformat ist application/atom+xml. Beispiel: "content-type":"application/json;odata=verbose"Specifies the format of the data that the client is sending to the server. The default format is application/atom+xml. Example: "content-type":"application/json;odata=verbose"
content-length-Headercontent-length header POST-Anforderungen, die Daten im Anforderungstextkörper senden (außer SP.RequestExecutor-Anforderungen)POST requests that send data in the request body (except SP.RequestExecutor requests) Gibt die Länge des Inhalts an. Beispiel: "content-length":requestBody.lengthSpecifies the length of the content. Example: "content-length":requestBody.length
IF-MATCH-HeaderIF-MATCH header POST-Anforderungen für DELETE-, MERGE- oder PUT-Vorgänge, in erster Linie, um Listen und Bibliotheken zu ändernPOST requests for DELETE, MERGE, or PUT operations, primarily for changing lists and libraries Bietet eine Möglichkeit, zu überprüfen, dass das Objekt, das geändert wird, seit seinem letzten Abruf nicht geändert wurde. Sie können aber auch festlegen, dass alle Änderungen überschrieben werden, wie im folgenden Beispiel zu sehen: "IF-MATCH":"*"Provides a way to verify that the object being changed has not been changed since it was last retrieved. Or, lets you specify to overwrite any changes, as shown in the following example: "IF-MATCH":"*"
X-HTTP-Method-HeaderX-HTTP-Method header POST fordert DELETE-, MERGE- oder PUT-Vorgänge anPOST requests for DELETE, MERGE, or PUT operations Wird verwendet, um festzulegen, dass die Anforderung einen Aktualisierungs- oder Löschvorgang durchführt. Beispiel: "X-HTTP-Method":"PUT"Used to specify that the request performs an update or delete operation. Example: "X-HTTP-Method":"PUT"
binaryStringRequestBodybinaryStringRequestBody SP.RequestExecutor- POST-Anforderungen, die binäre Daten im Anforderungstextkörper sendenSP.RequestExecutor POST requests that send binary data in the body Gibt an, ob der Anforderungstextkörper eine binäre Zeichenfolge ist. Boolean.Specifies whether the request body is a binary string. Boolean.
binaryStringResponseBodybinaryStringResponseBody SP.RequestExecutor-Anforderungen, die binäre Daten zurückgebenSP.RequestExecutor requests that return binary data Gibt an, ob die Antwort eine binäre Zeichenfolge ist. Boolean.Specifies whether the response is a binary string. Boolean.

Unterstützung für BatchaufträgeBatch job support

Der SharePoint Online-REST-Dienst (sowie der REST-Dienst von lokalem SharePoint 2016 und 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.The SharePoint Online (and on-premises SharePoint 2016 and later) REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. For details and links to code samples, see Make batch requests with the REST APIs.

Siehe auchSee also