WindowOrWorkerGlobalScope.fetch()

fetch()WindowOrWorkerGlobalScope ミックスインのメソッドで、ネットワークからリソースを取得するプロセスを開始し、レスポンスが利用できるようになったら満足するプロミスを返します。このプロミスはリクエストに対するレスポンスを表す Response で解決します。プロミスは HTTP エラーでは拒否されず、ネットワークエラーでのみ拒否されます。 HTTP エラーをチェックするには、 then ハンドラーを使用する必要があります。

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

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

fetch() メソッドは取得するリソースのディレクティブではなく Content Security Policyconnect-src ディレクティブによって制御されます。

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

構文

const fetchResponsePromise = fetch(resource [, init])

引数

resource
取得したいリソースを定義します。以下の 2 つが使用出来ます。
  • 取得したいリソースの直接の URL を含む USVString。ブラウザーによってはスキームとして blob:data: を受け入れます。
  • Request オブジェクト。
init Optional

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

method
リクエストするメソッド、GETPOST など。なお、 Origin ヘッダーは HEAD または GET メソッドの読み取りリクエストでは設定されません。
(この動作は Firefox 65 で修正されました — バグ 1508661 を参照)
headers
リクエストに追加したいヘッダーで、Headers オブジェクトか ByteString 値を持つオブジェクトリテラルで指定してください。なお、一部の名前は禁止されています
body
リクエストに追加したい本文です。これには Blob, BufferSource, FormData, URLSearchParams, USVString, ReadableStream オブジェクトなどが使用できます。メソッドが GETHEAD の場合使用できないので注意してください。
mode
リクエストで使いたいモードです。例: cors, no-cors, same-origin
credentials
リクエストに使用したいリクエスト認証情報、 omit, same-origin, include です。現在のドメインの Cookie を自動で送るためにはこのオプションを指定する必要があります。 Chrome 50 から、このプロパティはFederatedCredential インスタンスや PasswordCredential インスタンスを受け付けるようになりました。
cache
使用したいリクエストのキャッシュモードです。
redirect
使用するリダイレクトモードです。 follow (自動でリダイレクトに従う)、 error (リダイレクトが起こった場合エラーを伴って中止する)、 manual (手動でリダイレクトを処理する)。Chrome の既定値は follow です (バージョン 47 より前の既定値は manual でした)。
referrer
USVString でリクエストのリファラーを指定します。これは同じオリジンの URL、 about:client、空文字列のいずれかを取ることができます。
referrerPolicy
リクエストで使用するリファラーポリシーを指定します。使用可能な値は、 no-referrer, no-referrer-when-downgrade, same-origin, origin, strict-origin, origin-when-cross-origin, strict-origin-when-cross-origin, or unsafe-url のいずれかです。
integrity
リソースに subresource integrity 値を含ませることが出来ます (例:sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=)。
keepalive
keepalive オプションはページより長生きするリクエストを許可するのに使われます。keepalive フラグつきの Fetch はNavigator.sendBeacon() API の置き換えです。
signal
AbortSignal オブジェクトのインスタンスです。つまり AbortController 経由で fetch リクエストと通信したり望む場合には中止したりできます。

返値

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

例外

AbortError
AbortController メソッドまたは abort() メソッドの呼び出しによりリクエストが中止された。
TypeError
指定された URL がユーザー認証情報を含んでいる。この情報は Authorization ヘッダーを用いて提供するべきです。

Fetch Request example リポジトリ (デモ: Fetch Request live) では Request オブジェクトを関連するコンストラクターを使って作成しています。その後 fetch() を呼んで取得しています。画像を fetch している時から適切な MIME タイプを与えるために response の Body.blob を実行し、適切に処理されます。そして ObjectURL を作成し <img> 要素に追加して表示させています。

const myImage = document.querySelector('img');

let myRequest = new Request('flowers.jpg');

fetch(myRequest)
.then(function(response) {
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  return response.blob();
})
.then(function(response) {
  let objectURL = URL.createObjectURL(response);
  myImage.src = objectURL;
});

Fetch with init then Request example リポジトリ (デモ: Fetch Request init live) では上記の内容に加えて、fetch() を呼び出すとき、初期化オブジェクト init を渡しています。

const myImage = document.querySelector('img');

let myHeaders = new Headers();
myHeaders.append('Content-Type', 'image/jpeg');

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

let myRequest = new Request('flowers.jpg');

fetch(myRequest, myInit).then(function(response) {
  // ... 
});

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

let myRequest = new Request('flowers.jpg', myInit);

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

const myInit = {
  method: 'GET',
  headers: {
    'Content-Type': 'image/jpeg'
  },
  mode: 'cors',
  cache: 'default'
};

let myRequest = new Request('flowers.jpg', myInit);

仕様書

仕様書 状態 備考
Fetch
fetch() の定義
現行の標準 最新の仕様では WindowOrWorkerGlobalScope の中で部分的に定義。
Fetch
fetch() の定義
現行の標準 初回定義
Credential Management Level 1 草案 FederatedCredential または PasswordCredential のインスタンスを init.credentials の値として追加。

ブラウザーの互換性

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
fetch
実験的
Chrome 完全対応 42Edge 完全対応 14Firefox 完全対応 39
完全対応 39
完全対応 34
無効
無効 From version 34: this feature is behind the dom.fetch.enable preference. To change preferences in Firefox, visit about:config.
完全対応 52
補足
補足 fetch() now defined on WindowOrWorkerGlobalScope mixin.
IE 未対応 なしOpera 完全対応 29
完全対応 29
完全対応 28
無効
無効 From version 28: this feature is behind the Experimental Web Platform Features preference.
Safari 完全対応 10.1WebView Android 完全対応 42Chrome Android 完全対応 42Firefox Android 完全対応 39
完全対応 39
完全対応 34
無効
無効 From version 34: this feature is behind the dom.fetch.enable preference. To change preferences in Firefox, visit about:config.
完全対応 52
補足
補足 fetch() now defined on WindowOrWorkerGlobalScope mixin.
Opera Android 完全対応 29
完全対応 29
完全対応 28
無効
無効 From version 28: this feature is behind the Experimental Web Platform Features preference.
Safari iOS 完全対応 10.3Samsung Internet Android 完全対応 4.0
Support for blob: and data:
実験的
Chrome 完全対応 48Edge 完全対応 79Firefox ? IE 未対応 なしOpera ? Safari ? WebView Android 完全対応 43Chrome Android 完全対応 48Firefox Android ? Opera Android ? Safari iOS ? Samsung Internet Android 完全対応 5.0
referrerPolicyChrome 完全対応 52Edge 完全対応 79Firefox 完全対応 52IE 未対応 なしOpera 完全対応 39Safari 完全対応 11.1WebView Android 完全対応 52Chrome Android 完全対応 52Firefox Android 完全対応 52Opera Android 完全対応 41Safari iOS 未対応 なしSamsung Internet Android 完全対応 6.0
signal
実験的
Chrome 完全対応 66Edge 完全対応 16Firefox 完全対応 57IE 未対応 なしOpera 完全対応 53Safari 完全対応 11.1WebView Android 完全対応 66Chrome Android 完全対応 66Firefox Android 完全対応 57Opera Android 完全対応 47Safari iOS 完全対応 11.3Samsung Internet Android 完全対応 9.0
Streaming response body
実験的
Chrome 完全対応 43Edge 完全対応 14Firefox 完全対応 あり
無効
完全対応 あり
無効
無効 This feature is behind the dom.streams.enabled preference and the javascript.options.streams preference. To change preferences in Firefox, visit about:config.
IE 未対応 なしOpera 完全対応 29Safari 完全対応 10.1WebView Android 完全対応 43Chrome Android 完全対応 43Firefox Android 未対応 なしOpera Android 未対応 なしSafari iOS 完全対応 10.3Samsung Internet Android 完全対応 4.0

凡例

完全対応  
完全対応
未対応  
未対応
実装状況不明  
実装状況不明
実験的。動作が変更される可能性があります。
実験的。動作が変更される可能性があります。
実装ノートを参照してください。
実装ノートを参照してください。
ユーザーが明示的にこの機能を有効にしなければなりません。
ユーザーが明示的にこの機能を有効にしなければなりません。

関連情報