fetch() グローバル関数

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

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

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

WindowOrWorkerGlobalScopeWindowWorkerGlobalScope の両方で実装されています。これはつまり fetch() メソッドは、リソースを取得したいと思うような大部分コンテキストで使用可能ということです。

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

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

構文

js
fetch(resource)
fetch(resource, options)

引数

resource

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

  • 文字列または文字列化できるその他のオブジェクト(URL オブジェクトを含む)。取得したいリソースの直接の URL を含む文字列です。
  • Request オブジェクト。
options 省略可

リクエストに適用したいカスタム設定を含むオブジェクト。可能なオプションは以下の通りです。

method

リクエストするメソッド、"GET""POST" など。既定値は "GET" です。 なお、 Origin ヘッダーは HEAD または GET メソッドの読み取りリクエストでは設定されません。 (この動作は Firefox 65 で修正されました。 Firefox バグ 1508661 を参照) RFC 9110 のメソッドのいずれかと大文字小文字を区別せずに照合する文字列は、自動的に大文字になります。 (PATCH のような)カスタムメソッドを使用したい場合は、自分で大文字にする必要があります。

headers

リクエストに追加したいヘッダーで、 Headers オブジェクトまたは String 値を持つオブジェクトリテラルで指定してください。 なお、一部の名前は禁止されています

メモ: HTTP の Authorization ヘッダーがリクエストに追加される場合がありますが、そのリクエストがオリジン間でリダイレクトされた場合は削除されます。

body

リクエストに追加したい本体です。これには Blob, ArrayBuffer, TypedArray, DataView, FormData, URLSearchParams, 文字列オブジェクトまたはリテラル、 ReadableStream オブジェクトなどが使用できます。これは最新の利用可能状況で、まだ実験的なものです。互換性情報を調べて、あなたがこれを使用できるかどうかを確認してください。メソッドが GETHEAD の場合は使用できないので注意してください。

mode

リクエストで使用するモードです。例えば corsno-corssame-origin などです。

credentials

ブラウザーが資格情報を使用して何を行うか(クッキーHTTP 認証項目、 TLS クライアント証明書)を制御します。以下の文字列のうちの何れかでなければなりません。

omit

リクエストから資格情報を除外し、レスポンスで返される資格情報(Set-Cookie ヘッダーなど)を無視するようブラウザーに指示します。

same-origin

同一オリジンの URL へのリクエストに資格情報を記載し、同一オリジンの URL からのレスポンスで送り返されるすべての資格情報を使用するようブラウザーに指示します。これが既定値です。

include

ブラウザーに、同一オリジンおよびオリジン間リクエストの両方に資格情報を記載し、レスポンスで送り返された資格情報を常に使用するように指示します。

メモ: 資格情報は単純な、そして「最終的な」オリジン間リクエストに記載することができますが、 CORS プリフライトリクエストには記載されるべきではありません。

cache

文字列で、このリクエストがブラウザーの HTTP キャッシュにどう作用するかを示します。利用可能な値は default, no-store, reload, no-cache, force-cache, only-if-cached で、 Request オブジェクトの cache プロパティの記事に記述されています。

redirect

リダイレクトレスポンスを取り扱う方法を示します。

follow

自動的にリダイレクトを行います。他の方法が指定されていない限り、リダイレクトモードは follow に設定されます。

error

リダイレクトが発生した場合は、エラーで中止します。

manual

呼び出し側は、レスポンスを別のコンテキストで処理する予定です。 詳しくは WHATWG fetch standard を参照してください。

referrer

文字列で、リクエストのリファラーを指定します。これは同じオリジンの URL、 about:client、空文字列のいずれかを取ることができます。

referrerPolicy

リクエストで使用するリファラーポリシーを指定します。使用可能な値は、 no-referrer, no-referrer-when-downgrade, same-origin, origin, strict-origin, origin-when-cross-origin, strict-origin-when-cross-origin, unsafe-url のいずれかです。

integrity

リクエストのサブリソース完全性の値を保持します(sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE= など)。

keepalive

keepalive オプションは、ページの終了後のリクエストを許可するのに使用されます。 keepalive フラグつきのフェッチは Navigator.sendBeacon() API の置き換えです。

signal

AbortSignal オブジェクトのインスタンスです。つまり AbortController 経由でフェッチリクエストと通信したり望む場合には中止したりできます。

priority

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

high

同じ種類の他のリクエストに対する優先度の高いフェッチリクエスト。

low

同じ種類の他のリクエストと相対した、優先度の低いフェッチリクエスト。

auto

同じ種類の他のリクエストに対するフェッチリクエストの優先度を自動的に決定します(既定値)。

返値

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

例外

AbortError DOMException

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

TypeError

以下の理由で発生します。

理由 失敗する例
ヘッダー名が無効である。
// "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' });
        
モードが不正(navigatewebsocket)。
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-safe に掲載されているメソッド('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");

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 with init then Request の例Fetch Request init のライブ版) では上記の内容に加えて、fetch() を呼び出すとき、初期化オブジェクト init を渡しています。

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

const myHeaders = new Headers();
myHeaders.append("Accept", "image/jpeg");

const myInit = {
  method: "GET",
  headers: myHeaders,
  mode: "cors",
  cache: "default",
};

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

fetch(myRequest, myInit).then((response) => {
  // …
});

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

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

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

js
const myInit = {
  method: "GET",
  headers: {
    Accept: "image/jpeg",
  },
  mode: "cors",
  cache: "default",
};

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

仕様書

Specification
Fetch Standard
# fetch-method

ブラウザーの互換性

BCD tables only load in the browser

関連情報