このページはコミュニティーの尽力で英語から翻訳されました。MDN Web Docsコミュニティーについてもっと知り、仲間になるにはこちらから。
RequestInit
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 で読み取ることができませんが、サービスワーカーでキャッシュし、横取りしたフェッチリクエストに対するレスポンスとして使用することができます。この状況ではリクエストが成功したかどうかがわからないため、キャッシュされたレスポンスをネットワークから更新できるキャッシュ戦略を採用すべきです（例えば、キャッシュ更新付きのキャッシュ優先など）。- メソッドは
navigateHTML ナビゲーションでのみ使用します。
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 |