Window: fetch() メソッド

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2017.

fetch() は Window インターフェイスのメソッドで、ネットワークからリソースを取得するプロセスを開始し、レスポンスが利用できるようになったら履行されるプロミスを返します。

このプロミスは、そのリクエストに対するレスポンスを表す Response で解決します。

fetch() のプロミスは、ネットワークエラーが発生した場合（普通は権限の問題があったときなど）のみ拒否されます。 fetch() のプロミスは、サーバーがエラーを示す HTTP ステータスコード（404、504 など）を返しても拒否されません。 代わりに、 then() ハンドラーで Response.ok や Response.status プロパティをチェックする必要があります。

fetch() メソッドは取得するリソースのディレクティブではなく、コンテンツセキュリティポリシーの connect-src ディレクティブによって制御されます。

メモ: fetch() メソッドの引数は Request() コンストラクターと全く同じです。

構文

js
fetch(resource)
fetch(resource, options)

引数

resource

取得したいリソースを定義します。以下のどちらかが使用できます。

  • 文字列または文字列化できるその他のオブジェクト（URL オブジェクトを含む）。取得したいリソースの直接の URL を含む文字列です。この URL は、文書内の baseURI、ワーカーコンテキストでは WorkerGlobalScope.location となります。
  • Request オブジェクト。
options 省略可

リクエストに適用する独自の設定を含む RequestInit オブジェクトです。

返値

Promise で、 Response オブジェクトに解決します。

例外

AbortError DOMException

AbortController の abort() メソッドの呼び出しによりリクエストが中止された。

NotAllowedError DOMException

トピック API を使用することが、権限ポリシーの browsing-topics によって特別に禁止されており、そして fetch() リクエストが browsingTopics: true で行われたときに発生します。

TypeError

以下の理由で発生する可能性があります。

理由 失敗する例
権限ポリシーによるブロック Attribution Reporting API の使用は、attribution-reporting Permissions-Policy で、fetch() リクエストが attributionReporting を指定して行われました。
ヘッダー名が無効である。 
// "C ontent-Type" に空白がある
const headers = {
  'C ontent-Type': 'text/xml',
  'Breaking-Bad': '<3',
};
fetch('https://example.com/', { headers });
ヘッダーの値が無効である。ヘッダーオブジェクトは正確に 2 つの要素を含まなければならない。 
const headers = [
  ['Content-Type', 'text/html', 'extra'],
  ['Accept'],
];
fetch('https://example.com/', { headers });
URL またはスキームが無効であるか、フェッチが対応していないスキームを使用しているか、または特定のリクエストモードに対応していないスキームを使用している。 
fetch('blob://example.com/', { mode: 'cors' });
URL に資格情報が入っている。 
fetch('https://user:password@example.com/');
リファラー URL が不正である。 
fetch('https://example.com/', { referrer: './abc\u0000df' });
モードが不正（navigate や websocket）。 
fetch('https://example.com/', { mode: 'navigate' });
リクエストキャッシュモードが "only-if-cached" で、かつリクエストモードが "same-origin" 以外の場合。 
fetch('https://example.com/', {
  cache: 'only-if-cached',
  mode: 'no-cors',
});
リクエストメソッドが無効な名前トークンである場合、または禁止されたヘッダー（'CONNECT', 'TRACE', 'TRACK'）の 1 つである場合。 
fetch('https://example.com/', { method: 'CONNECT' });
リクエストモードが "no-cors" であり、リクエストメソッドが CORS セーフリストに掲載されているメソッド（'GET', 'HEAD', 'POST'）でない場合。 
fetch('https://example.com/', {
  method: 'CONNECT',
  mode: 'no-cors',
});
リクエストメソッドが 'GET' または 'HEAD' で、本体が null でないか、 undefined でない場合。 
fetch('https://example.com/', {
  method: 'GET',
  body: new FormData(),
});
fetch がネットワークエラーを発生した場合。

例

Fetch Request の例（Fetch Request のライブ版を参照）では、 Request オブジェクトを関連するコンストラクターで作成しています。その後で fetch() を呼び出して取得しています。画像を読み取っているため、レスポンスで Response.blob() を実行して正しい MIME タイプを指定して正しく扱われるようにし、オブジェクト URL を作成して <img> 要素に追加して表示させています。

js
const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

window
  .fetch(myRequest)
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    return response.blob();
  })
  .then((response) => {
    myImage.src = URL.createObjectURL(response);
  });

Fetch Request with init の例（Fetch Request init のライブ版）では上記の内容に加えて、fetch() を呼び出すとき、初期化オブジェクト init を渡しています。 この場合、Cache-Control 値を設定することで、どのようなキャッシュレスポンスであれば問題ないかを示すことができます。

js
const myImage = document.querySelector("img");
const reqHeaders = new Headers();

// キャッシュされたレスポンスは、それが 1 週間以上前のものでなければ問題ない
reqHeaders.set("Cache-Control", "max-age=604800");

const options = {
  headers: reqHeaders,
};

// init をヘッダーと一緒に "options" オブジェクトとして渡す
const req = new Request("flowers.jpg", options);

fetch(req).then((response) => {
  // ...
});

同様に init オブジェクトを Request コンストラクターに渡しても、同じ効果が得られます。

js
const req = new Request("flowers.jpg", options);

init の headers でオブジェクトリテラルを使用することもできます。

js
const options = {
  headers: {
    "Cache-Control": "max-age=60480",
  },
};

const req = new Request("flowers.jpg", options);

仕様書

Specification
Fetch Standard
# fetch-method

ブラウザーの互換性

BCD tables only load in the browser

関連情報