GlobalFetch.fetch()

GlobalFetch インターフェイスの fetch() メソッドはネットワークからリソースの fetch (取得) を開始します。このメソッドはリクエストのレスポンスを表す Response オブジェクトの Promise を返します 。

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

fetch() の promise はネットワークエラーの場合 TypeError として reject 状態になるでしょう。しかし、TypeError は普通パーミッションの問題やそれに似た問題で発生します。fetch() が成功かどうかの精密なチェックとして promise が resolved かどうかを確認しその後 Response.ok プロパティがtrue かどうかを確認します。HTTP status コードが 404 の場合ネットワークエラーには含まれません。

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

構文

Promise<Response> fetch(input[, init]);

引数

input

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

• fetch したい URL を含む USVString いくつかのブラウザーでは、スキームとして blob: と data: を受け入れます
• Request オブジェクト。

init Optional

リクエストに適用したい設定を含むオプションの (必須ではない) オブジェクトです。以下のオプションが使用できます。

• method: リクエストするメソッド、GET、POST など。
• headers: リクエストに追加したいヘッダー、Headers オブジェクトか ByteString 値を持つオブジェクトリテラルで指定してください。
• body: リクエストに追加したいボディ、Blob、BufferSource、FormData、URLSearchParams もしくは USVString オブジェクトなどが使用できます。method が GET や HEAD の場合使用できないので注意してください。
• mode: リクエストで使いたいモードです。例: cors、no-cors, or same-origin。
• credentials: request に使用したい秘密情報: omit、same-origin、include が使用可能です。現在のドメインの Cookie を自動で送るためにはこのオプションを指定する必要があります。Chrome 50 から、このプロパティはFederatedCredential インスタンスや PasswordCredential インスタンスを受け付けるようになりました。
• cache: 使用したいリクエストのキャッシュのモードを指定できます: default、no-store、reload、no-cache、force-cache、only-if-cached などのモードが使用できます。
• redirect: リダイレクトをどう処理するかについて次の値を取ることができます: follow (自動でリダイレクトに従う)、error (リダイレクトが起こった場合エラーを伴って中止する)、manual (手動でリダイレクトを処理する)。Chrome のデフォルト値は follow です(バージョン 47 より前はデフォルト値は manual でした)。
• referrer: USVString の no-referrer、client、URL。デフォルトは client です。
• referrerPolicy: リファラー HTTP ヘッダーを指定します。次のオプションが使用可能です。no-referrer、no-referrer-when-downgrade、origin、origin-when-cross-origin、unsafe-url。
• integrity: リソースに subresource integrity 値を含ませることが出来ます (例：sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=)。
• keepalive: keepalive オプションはページより長生きするリクエストを許可するのに使われます。keepalive フラグありのFetchはNavigator.sendBeacon() APIの置き換えです。
• signal: AbortSignal オブジェクトのインスタンスです。つまり AbortController 経由で fetch リクエストと通信したり望む場合には中止したりできます。

返り値

解決時に Response オブジェクトを取得できる Promise オブジェクト。

例外

例

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

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

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

fetch(myRequest).then(function(response) {
  return response.blob();
}).then(function(response) {
  var objectURL = URL.createObjectURL(response);
  myImage.src = objectURL;
});

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

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

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

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

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

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

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

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

init 内に、オブジェクトリテラルをヘッダーとして使う事もできます。

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

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

仕様

ブラウザー実装状況

関連項目

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