RequestInit

We’d love to hear your thoughts on the next set of proposals for the JavaScript language. You can find a description of the proposals here.

Please take two minutes to fill out our short survey.

RequestInit はフェッチ API の辞書で、フェッチリクエストを構成するのに使用する一連のオプションを表します。

RequestInit オブジェクトは Request() コンストラクターに渡したり、直接 fetch() 関数呼び出しに渡したりすることができます。

また、Request を RequestInit で作成し、その Request を fetch() に別の RequestInit と一緒に渡すこともできます。この場合、両方の場所で同じオプションが設定されていれば、直接 fetch() に渡された値が使用されます。

インスタンスプロパティ

attributionReporting 省略可 Experimental

このリクエストのレスポンスに JavaScript ベースの帰属ソースまたは帰属トリガーを登録できるようにしたいことを示します。attributionReporting は以下のプロパティを格納するオブジェクトです。

eventSourceEligible: 論理値。true に設定すると、このリクエストのレスポンスは帰属ソースの登録の対象となります。false に設定すると、対象になりません。
triggerEligible: 論理値。true に設定すると、このリクエストのレスポンスは帰属トリガーの登録の対象となります。false に設定すると、対象になりません。

詳しくは Attribution Reporting API を参照してください。

body 省略可

サーバーに送信する内容を含むリクエスト本体です。例えば POST または PUT リクエストで使用されます。以下のいずれかの型のインスタンスとして指定します。

詳しくは本体の設定を参照してください。

browsingTopics 省略可 Experimental

論理値で、現在のユーザーのために選択されたトピックを、リクエストに関連付けられた Sec-Browsing-Topics ヘッダーで送ることを指定します。

詳しくは Using the Topics API を参照してください。

cache 省略可

リクエストに使用したいキャッシュモードを指定します。以下の値のいずれかを指定します。

default

ブラウザーはリクエストに一致するレスポンスを HTTP キャッシュから探します。

一致したものがあり新しい場合、それをキャッシュから返します。
もし一致するものがあっても古い場合は、ブラウザーはリモートサーバーに条件付きリクエストを行います。サーバーがリソースが変更されていないことを示した場合、そのリソースはキャッシュから返されます。そうでなければ、リソースはサーバーからダウンロードされ、キャッシュが更新されます。
一致するものがない場合、ブラウザーは通常のリクエストを行い、ダウンロードされたリソースでキャッシュを更新します。

no-store

ブラウザーは最初にキャッシュを見ずにリモートサーバーからリソースを取得し、ダウンロードしたリソースでキャッシュを更新しません。

reload

ブラウザーは最初のキャッシュを見ずにリモートサーバーからリソースを取得しますが、ダウンロードしたリソースでキャッシュを更新します。

no-cache

ブラウザーは、リクエストに一致するレスポンスがないか、HTTP キャッシュを探します。

一致するものがあれば、新しいか古いかを問わず、ブラウザーはリモートサーバーに条件付きリクエストを行います。サーバーがリソースが変更されていないことを示した場合、そのリソースはキャッシュから返されます。そうでなければ、リソースはサーバーからダウンロードされ、キャッシュが更新されます。
一致するものがない場合、ブラウザーは通常のリクエストを行い、ダウンロードされたリソースでキャッシュを更新します。

force-cache

ブラウザーは、リクエストに一致するレスポンスを HTTP キャッシュから探します。

一致するものがあれば、新しいか古いかを問わず、それをキャッシュから返します。
一致するものがない場合、ブラウザーは通常のリクエストを行い、ダウンロードされたリソースでキャッシュを更新します。

only-if-cached

ブラウザーは、リクエストに一致するレスポンスを HTTP キャッシュから探します。 Experimental

一致するものがあれば、新しいか古いかを問わず、それをキャッシュから返します。
一致するものがない場合は、ネットワークエラーを返します。

"only-if-cached" モードはリクエストの mode が "same-origin" である場合にのみ使用することができます。リクエストの redirect プロパティが "follow" で、かつ "same-origin" モードに違反していなければ、キャッシュされたリダイレクトに従います。

credentials 省略可

ブラウザーがリクエストと共に資格情報を送るかどうか、また Set-Cookie レスポンスヘッダーを尊重するかどうかを制御します。資格情報とはクッキー、TLS クライアント証明書、またはユーザー名とパスワードを格納した認証ヘッダーです。このオプションには以下の任意の値が指定できます。

omit: リクエストで資格情報を送信したり、レスポンスに資格情報を含めたりしません。
same-origin: 同一オリジンのリクエストに対してのみ資格情報を送信し、含めます。
include: オリジン間リクエストであっても、常に資格情報を含めます。

オリジン間のリクエストに資格情報を含めると、CSRF 攻撃を受けやすくなる可能性があります。そのため、credentials が include に設定されていても、Access-Control-Allow-Credentials をレスポンスに含めることで、サーバーも資格情報を含めることに同意する必要があります。さらに、この状況ではサーバーはAccess-Control-Allow-Origin レスポンスヘッダーでクライアントのオリジンのサーバーを明示的に指定しなければなりません（つまり、* は許可されません）。

詳しくは資格情報を含めるを参照してください。

既定値は same-origin です。

headers 省略可

リクエストに追加したいヘッダーで、 Headers オブジェクト、またはキーがヘッダー名で値がヘッダー値であるオブジェクトリテラルが入ります。

多くのヘッダーはブラウザーによって自動的に設定され、スクリプトによって設定することはできません。これらは禁止ヘッダー名と呼ばれています。

mode オプションが no-cors に設定されている場合、CORS セーフリストリクエストヘッダーのみを設定することができます。

詳しくはヘッダーの設定を参照してください。

integrity 省略可

このリクエストのサブリソース完全性の値を保持します。

これは <script> 要素に integrity 属性を設定したときと同じように、リソースをフェッチしたときに調べられます。ブラウザーはフェッチされたリソースの hash を指定されたアルゴリズムで計算し、その結果が指定された値と一致しない場合、ネットワークエラーでフェッチリクエストを拒否します。

このオプションは <hash-algo>-<hash-source> という書式です。

<hash-algo> は sha256、sha384、sha512 のいずれかです。
<hash-source> は指定したハッシュアルゴリズムでリソースをハッシュした結果の Base64 エンコーディングです。

既定値は空文字列です。

keepalive 省略可

論理値。 true に設定すると、リクエストが完全に完了する前にリクエストを開始したページが読み込まれなくなった場合でも、関連付けられたリクエストが中止されなくなります。これにより、ユーザーがページから離れたり閉じたりした場合でも、 fetch() リクエストによりセッションの終わりに分析データを送信することができます。

これは、同じ目的で Navigator.sendBeacon() を使用するよりもいくつかの利点があります。例えば、 POST 以外の HTTP メソッドを使用することができます。また、リクエストプロパティをカスタマイズしたり、フェッチのプロミス (Promise) の履行を通じて、サーバーレスポンスにアクセスしたりすることができます。サービスワーカーでも利用可能です。

keepalive リクエストの本体サイズは 64 キロバイトに制限されています。

既定値は false です。

method 省略可

リクエストメソッドです。

既定値は GET です。

mode 省略可

オリジン間リクエストの動作を設定します。以下の値のいずれかです。

same-origin

オリジン間リクエストを許可しません。 same-origin リクエストが異なるオリジンに送信された場合、ネットワークエラーが発生します。

cors

このリクエストがオリジン間リクエストであった場合、オリジン間リソース共有 (CORS) の仕組みを使用します。 CORS セーフリストレスポンスヘッダーのみがレスポンスに公開されます。

no-cors

オリジン間リクエストで CORS を無効にします。このオプションには、次の制限があります。

メソッドは HEAD、GET、POST のいずれかである必要があります。
ヘッダーは CORS セーフリストリクエストヘッダーのみですが、さらなる制約として Range ヘッダーも許可されません。これはサービスワーカーが追加したヘッダーにも適用されます。
レスポンスは不透明となり、ヘッダーと本体は JavaScript から利用できず、ステータスコードは常に 0 になります。

no-cors の主な適用例はサービスワーカーです。 no-cors リクエストに対するレスポンスは JavaScript で読み取ることができませんが、サービスワーカーでキャッシュし、横取りしたフェッチリクエストに対するレスポンスとして使用することができます。この状況ではリクエストが成功したかどうかがわからないため、キャッシュされたレスポンスをネットワークから更新できるキャッシュ戦略を採用すべきです（例えば、キャッシュ更新付きのキャッシュ優先など）。

navigate

HTML ナビゲーションでのみ使用します。navigate リクエストは文書間を移動するときにのみ作成されます。

詳しくは、オリジン間リクエストを行うを参照してください。

既定値は cors です。

priority 省略可

同じ種類の他のリクエストに対する、この読み込みリクエストの優先度を指定します。以下の文字列のいずれかでなければなりません。

high: 同じ種類の他のリクエストに対する優先度の高いフェッチリクエスト。
low: 同じ種類の他のリクエストと相対した、優先度の低いフェッチリクエスト。
auto: フェッチの優先度をユーザーが設定しません。これは値を設定しない場合や無効な値が設定された場合に使用されます。

既定値は auto です。

redirect 省略可

サーバーがリダイレクトステータスでレスポンスした場合のブラウザー動作を決定します。以下の値のいずれかです。

follow: 自動的にリダイレクトを行います。
error: リダイレクトステータスを返ると、ネットワークエラーでプロミスを拒否します。
manual: ほとんどすべてのフィールドがフィルターされたレスポンスを返し、サービスワーカーがそのレスポンスを格納して、後で再生できるようにします。

既定値は follow です。

referrer 省略可

リクエストの Referer ヘッダーに使用する値を指定する文字列。以下のいずれかを指定します。

同じオリジンの相対 URL または絶対 URL: 参照するヘッダー Referer を指定された値に設定します。相対 URL はリクエストを行ったページの URL に対して相対的に解決されます。
空文字列: Referer ヘッダーを除外します。
about:client: ヘッダー Referer にはリクエストのコンテキスト（例えばリクエストを行ったページの URL）の既定値を設定します。

既定値は about:client です。

referrerPolicy 省略可

文字列で、Referer ヘッダーのポリシーを設定します。このオプションの構文と意味づけは Referrer-Policy ヘッダーの場合とまったく同じです。

signal 省略可

AbortSignal です。このオプションを設定すると、対応する AbortController で abort() を呼び出すことでリクエストを中止することができます。

例

`fetch()` にオプションを渡す

この例では、method、body、headers オプションを fetch() メソッド呼び出しに直接渡しています。

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

`Request()` コンストラクターにオプションを渡す

この例では Request を作成し、そのコンストラクターに同じオプション設定をして fetch() にリクエストを渡します。

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

`Request()` と `fetch()` の両方にオプションを渡す

この例では Request を作成し、 method、headers、body オプションをコンストラクターに渡します。そして、body と referrer オプションとともに fetch() にリクエストを渡します。

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

この場合、リクエストは以下のオプションと共に送信されます。

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

仕様書

Specification
Fetch # requestinit

インスタンスプロパティ

例

fetch() にオプションを渡す

Request() コンストラクターにオプションを渡す

Request() と fetch() の両方にオプションを渡す

仕様書

関連情報

`fetch()` にオプションを渡す

`Request()` コンストラクターにオプションを渡す

`Request()` と `fetch()` の両方にオプションを渡す