WindowOrWorkerGlobalScope.fetch()

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

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

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

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

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

構文

const fetchResponsePromise = fetch(resource [, init])

引数

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

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

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 (en-US) インスタンスを受け付けるようになりました。
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 (en-US) 経由で fetch リクエストと通信したり望む場合には中止したりできます。

返値

Promise (en-US) で、 Response オブジェクトに解決します。

例外

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

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

ブラウザーの互換性

No compatibility data found for api.WindowOrWorkerGlobalScope.fetch.
Check for problems with this page or contribute missing data to mdn/browser-compat-data.

関連情報