RequestInit

Das RequestInit-Wörterbuch der Fetch API repräsentiert die Menge von Optionen, die verwendet werden können, um eine fetch-Anfrage zu konfigurieren.

Sie können ein RequestInit-Objekt in den Request()-Konstruktor oder direkt in den Funktionsaufruf von fetch() übergeben.

Sie können auch ein Request mit einem RequestInit erstellen und das Request an einen fetch()-Aufruf zusammen mit einem anderen RequestInit übergeben. Wenn Sie dies tun und dieselbe Option an beiden Stellen festgelegt wird, wird der Wert verwendet, der direkt in fetch() übergeben wird.

Instanz-Eigenschaften

attributionReporting Optional

Gibt an, dass die Antwort der Anfrage in der Lage sein soll, eine JavaScript-basierte Attributionsquelle oder einen Attribution Trigger zu registrieren. attributionReporting ist ein Objekt, das die folgenden Eigenschaften enthält:

eventSourceEligible

Ein boolescher Wert. Wenn auf true gesetzt, ist die Antwort der Anfrage geeignet, eine Attributionsquelle zu registrieren. Wenn auf false gesetzt, ist sie es nicht.

triggerEligible

Ein boolescher Wert. Wenn auf true gesetzt, ist die Antwort der Anfrage geeignet, einen Attribution Trigger zu registrieren. Wenn auf false gesetzt, ist sie es nicht.

Weitere Informationen finden Sie in der Attribution Reporting API.

body Optional

Der Anfrageinhalt enthält die Daten, die an den Server gesendet werden sollen, zum Beispiel in einer POST oder PUT-Anfrage. Er wird als Instanz eines der folgenden Typen angegeben:

Weitere Details finden Sie unter Setting a body.

browsingTopics Optional

Ein boolescher Wert, der angibt, dass die ausgewählten Themen für den aktuellen Benutzer in einem Sec-Browsing-Topics-Header mit der zugehörigen Anfrage gesendet werden sollten.

Weitere Informationen finden Sie unter Using the Topics API.

cache Optional

Der Cache-Modus, den Sie für die Anfrage verwenden möchten. Dies kann einer der folgenden Werte sein:

default

Der Browser durchsucht seinen HTTP-Cache nach einer Antwort, die der Anfrage entspricht.

  • Wenn es eine Übereinstimmung gibt und diese aktuell ist, wird sie aus dem Cache zurückgegeben.
  • Wenn es eine Übereinstimmung gibt, diese jedoch veraltet ist, stellt der Browser eine bedingte Anfrage an den Remoteserver. Wenn der Server angibt, dass sich die Ressource nicht verändert hat, wird sie aus dem Cache zurückgegeben. Andernfalls wird die Ressource vom Server heruntergeladen und der Cache wird aktualisiert.
  • Wenn es keine Übereinstimmung gibt, stellt der Browser eine normale Anfrage und aktualisiert den Cache mit der heruntergeladenen Ressource.
no-store

Der Browser holt die Ressource vom Remoteserver, ohne zuerst im Cache nachzusehen, und wird den Cache nicht mit der heruntergeladenen Ressource aktualisieren.

reload

Der Browser holt die Ressource vom Remoteserver, ohne zuerst im Cache nachzusehen, wird jedoch den Cache mit der heruntergeladenen Ressource aktualisieren.

no-cache

Der Browser durchsucht seinen HTTP-Cache nach einer Antwort, die der Anfrage entspricht.

  • Wenn es eine Übereinstimmung gibt, aktuell oder veraltet, wird der Browser eine bedingte Anfrage an den Remoteserver stellen. Wenn der Server angibt, dass sich die Ressource nicht verändert hat, wird sie aus dem Cache zurückgegeben. Andernfalls wird die Ressource vom Server heruntergeladen und der Cache wird aktualisiert.
  • Wenn es keine Übereinstimmung gibt, stellt der Browser eine normale Anfrage und aktualisiert den Cache mit der heruntergeladenen Ressource.
force-cache

Der Browser durchsucht seinen HTTP-Cache nach einer Antwort, die der Anfrage entspricht.

  • Wenn es eine Übereinstimmung gibt, aktuell oder veraltet, wird sie aus dem Cache zurückgegeben.
  • Wenn es keine Übereinstimmung gibt, stellt der Browser eine normale Anfrage und aktualisiert den Cache mit der heruntergeladenen Ressource.
only-if-cached

Der Browser durchsucht seinen HTTP-Cache nach einer Antwort, die der Anfrage entspricht.

  • Wenn es eine Übereinstimmung gibt, aktuell oder veraltet, wird sie aus dem Cache zurückgegeben.
  • Wenn es keine Übereinstimmung gibt, wird ein Netzwerkfehler zurückgegeben.

Der Modus "only-if-cached" kann nur verwendet werden, wenn der mode der Anfrage "same-origin" ist. Zwischengespeicherte Umleitungen werden verfolgt, wenn die redirect-Eigenschaft der Anfrage auf "follow" gesetzt ist und die Umleitungen nicht gegen den "same-origin"-Modus verstoßen.

credentials Optional

Legt fest, ob der Browser Anmeldedaten mit der Anfrage sendet und ob Set-Cookie-Antwortheader beachtet werden. Anmeldedaten sind Cookies, TLS-Client-Zertifikate oder Authentifizierungsheader, die einen Benutzernamen und ein Passwort enthalten. Diese Option kann einer der folgenden Werte sein:

omit

Nie Anmeldedaten in der Anfrage senden oder Anmeldedaten in der Antwort berücksichtigen.

same-origin

Nur Anmeldedaten für Anfragen aus demselben Ursprung senden und berücksichtigen.

include

Immer Anmeldedaten einschließen, selbst bei Cross-Origin-Anfragen.

Das Einschließen von Anmeldedaten bei Cross-Origin-Anfragen kann eine Website anfällig für CSRF-Angriffe machen. Selbst wenn credentials auf include gesetzt ist, muss der Server auch deren Einbeziehung akzeptieren, indem er den Access-Control-Allow-Credentials-Header in seine Antwort einfügt. Zusätzlich muss der Server in diesem Fall den Ursprungsort des Clients explizit in seinem Access-Control-Allow-Origin-Antwortheader angeben (das heißt, * ist nicht erlaubt).

Weitere Details finden Sie unter Including credentials.

Standardmäßig auf same-origin gesetzt.

headers Optional

Alle Header, die Sie zu Ihrer Anfrage hinzufügen möchten, enthalten in einem Headers-Objekt oder einem Objektliteral, dessen Schlüssel die Namen der Header und dessen Werte die Headerwerte sind.

Viele Header werden automatisch vom Browser gesetzt und können von einem Skript nicht gesetzt werden: Diese werden als Verbotene Anforderungsüberschriften bezeichnet.

Wenn die mode-Option auf no-cors gesetzt ist, können nur CORS-freigegebene Anforderungsüberschriften gesetzt werden.

Weitere Details finden Sie unter Setting headers.

integrity Optional

Enthält den Wert der Subressourcen-Integrität der Anfrage.

Dies wird beim Abruf der Ressource überprüft, genau wie wenn das integrity-Attribut auf einem <script>-Element gesetzt ist. Der Browser berechnet den Hash der abgerufenen Ressource mit dem angegebenen Algorithmus und lehnt die Abrufanfrage mit einem Netzwerkfehler ab, wenn das Ergebnis nicht mit dem angegebenen Wert übereinstimmt.

Das Format dieser Option ist <hash-algo>-<hash-source>, wobei:

  • <hash-algo> einer der folgenden Werte ist: sha256, sha384 oder sha512
  • <hash-source> die Base64-Kodierung des Ergebnisses der Hash-Berechnung der Ressource mit dem angegebenen Hash-Algorithmus ist.

Standardmäßig auf einen leeren String gesetzt.

keepalive Optional

Ein boolescher Wert. Wenn auf true gesetzt, wird der Browser die zugehörige Anfrage nicht abbrechen, wenn die Seite, die sie initiiert hat, entladen wird, bevor die Anfrage abgeschlossen ist. Dies ermöglicht es einer fetch()-Anfrage, am Ende einer Sitzung Analysen zu senden, auch wenn der Benutzer die Seite verlässt oder schließt.

Dies bietet einige Vorteile gegenüber der Verwendung von Navigator.sendBeacon() für denselben Zweck. Zum Beispiel können Sie andere HTTP-Methoden als POST verwenden, Anfrageeigenschaften anpassen und auf die Serverantwort über die Erfüllung des fetch-Promise zugreifen. Es ist auch in Service Workern verfügbar.

Die Körpergröße für keepalive-Anfragen ist auf 64 Kibibytes begrenzt.

Standardmäßig auf false gesetzt.

method Optional

Die Anfragemethode.

Standardmäßig auf GET gesetzt.

mode Optional

Legt das Cross-Origin-Verhalten für die Anfrage fest. Einer der folgenden Werte:

same-origin

Verhindert Cross-Origin-Anfragen. Wenn eine same-origin-Anfrage an einen anderen Ursprung gesendet wird, ist das Ergebnis ein Netzwerkfehler.

cors

Wenn die Anfrage cross-origin ist, wird sie das Cross-Origin Resource Sharing (CORS)-Mechanismus verwenden. Es werden nur CORS-freigegebene Antwortüberschriften in der Antwort offengelegt.

no-cors

Deaktiviert CORS für Cross-Origin-Anfragen. Diese Option ist mit den folgenden Einschränkungen verbunden:

  • Die Methode darf nur eine von HEAD, GET oder POST sein.
  • Die Header dürfen nur CORS-freigegebene Anforderungsüberschriften sein, mit der zusätzlichen Einschränkung, dass der Range-Header ebenfalls nicht erlaubt ist. Dies gilt auch für alle Header, die von Service Workern hinzugefügt werden.
  • Die Antwort ist undurchsichtig, was bedeutet, dass ihre Header und ihr Inhalt JavaScript nicht zur Verfügung stehen, und ihr Statuscode ist immer 0.

Die Hauptanwendung für no-cors ist für einen Service Worker: obwohl die Antwort auf eine no-cors-Anfrage von JavaScript nicht gelesen werden kann, kann sie von einem Service Worker zwischengespeichert und dann als Antwort auf eine abgefangene Fetch-Anfrage verwendet werden. Beachten Sie, dass Sie in dieser Situation nicht wissen, ob die Anfrage erfolgreich war oder nicht, daher sollten Sie eine Caching-Strategie anwenden, die es ermöglicht, die zwischengespeicherte Antwort aus dem Netzwerk zu aktualisieren (wie zum Beispiel cache first with cache refresh).

Wird nur von HTML-Navigation verwendet. Eine navigate-Anfrage wird nur beim Navigieren zwischen Dokumenten erstellt.

Weitere Informationen finden Sie unter Making cross-origin requests.

Standardmäßig auf cors gesetzt.

priority Optional

Gibt die Priorität der Fetch-Anfrage im Verhältnis zu anderen Anfragen desselben Typs an. Muss einer der folgenden Werte sein:

high

Eine Fetch-Anfrage mit hoher Priorität im Verhältnis zu anderen Anfragen desselben Typs.

low

Eine Fetch-Anfrage mit niedriger Priorität im Verhältnis zu anderen Anfragen desselben Typs.

auto

Keine Benutzervorgabe für die Fetch-Priorität. Es wird verwendet, wenn kein Wert gesetzt oder ein ungültiger Wert gesetzt wird.

Standardmäßig auf auto gesetzt.

redirect Optional

Bestimmt das Verhalten des Browsers, wenn der Server mit einem Umleitungsstatus antwortet. Einer der folgenden Werte:

follow

Umleitungen automatisch folgen.

error

Verspricht mit einem Netzwerkfehler ablehnen, wenn ein Umleitungsstatus zurückgegeben wird.

manual

Eine Antwort zurückgeben, bei der fast alle Felder gefiltert sind, um einem Service Worker zu ermöglichen, die Antwort zu speichern und später wiederzugeben.

Standardmäßig auf follow gesetzt.

referrer Optional

Ein String, der den Wert angibt, der für den Referer-Header der Anfrage verwendet werden soll. Einer der folgenden:

Eine gleichursprüngliche relative oder absolute URL

Setzt den Referer-Header auf den angegebenen Wert. Relative URLs werden relativ zur URL der Seite, die die Anfrage gestellt hat, aufgelöst.

Ein leerer String

Den Referer-Header weglassen.

about:client

Setzt den Referer-Header auf den Standardwert für den Kontext der Anfrage (zum Beispiel die URL der Seite, die die Anfrage gestellt hat).

Standardmäßig auf about:client gesetzt.

referrerPolicy Optional

Ein String, der eine Richtlinie für den Referer-Header festlegt. Die Syntax und Semantik dieser Option sind genau die gleichen wie für den Referrer-Policy-Header.

signal Optional

Ein AbortSignal. Wenn diese Option gesetzt ist, kann die Anfrage durch Aufrufen von abort() am entsprechenden AbortController abgebrochen werden.

Beispiele

Optionen in fetch() übergeben

In diesem Beispiel geben wir die Optionen method, body und headers direkt in den Methodenaufruf von fetch() ein:

js
async function post() {
  const response = await fetch("https://example.org/post", {
    method: "POST",
    body: JSON.stringify({ username: "example" }),
    headers: {
      "Content-Type": "application/json",
    },
  });

  console.log(response.status);
}

Optionen in den Request()-Konstruktor übergeben

In diesem Beispiel erstellen wir eine Request, indem wir denselben Satz von Optionen in deren Konstruktor übergeben, und übergeben dann die Anfrage an fetch():

js
async function post() {
  const request = new Request("https://example.org/post", {
    method: "POST",
    body: JSON.stringify({ username: "example" }),
    headers: {
      "Content-Type": "application/json",
    },
  });

  const response = await fetch(request);

  console.log(response.status);
}

Optionen sowohl in Request() als auch in fetch() übergeben

In diesem Beispiel erstellen wir eine Request, indem wir die Optionen method, headers und body in deren Konstruktor übergeben. Wir übergeben dann die Anfrage an fetch() zusammen mit den Optionen body und referrer:

js
async function post() {
  const request = new Request("https://example.org/post", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ username: "example1" }),
  });

  const response = await fetch(request, {
    body: JSON.stringify({ username: "example2" }),
    referrer: "",
  });

  console.log(response.status);
}

In diesem Fall wird die Anfrage mit den folgenden Optionen gesendet:

  • method: "POST"
  • headers: {"Content-Type": "application/json"}
  • body: '{"username":"example2"}'
  • referrer: ""

Spezifikationen

Specification
Fetch
# requestinit

Siehe auch