WindowOrWorkerGlobalScope.fetch()

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

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

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

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

構文

const fetchResponsePromise = fetch(resource [, init])

引数

resource

取得したいリソースを定義します。以下の 2 つが使用出来ます。

• 取得したいリソースの直接の URL を含む USVString。ブラウザーによってはスキームとして blob: と data: を受け入れます。
• Request オブジェクト。

init Optional

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

method

リクエストするメソッド、GET、POST など。なお、 Origin ヘッダーは HEAD または GET メソッドの読み取りリクエストでは設定されません。
(この動作は Firefox 65 で修正されました — バグ 1508661 を参照)

headers

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

body

リクエストに追加したい本文です。これには Blob, BufferSource, FormData, URLSearchParams, USVString, ReadableStream オブジェクトなどが使用できます。メソッドが GET や HEAD の場合使用できないので注意してください。

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);

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

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

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

仕様書

ブラウザーの互換性

関連情報

• Fetch API
• ServiceWorker API
• HTTP access control (CORS)
• HTTP