{{APIRef("Fetch API")}}
fetch() は {{domxref("WindowOrWorkerGlobalScope")}} ミックスインのメソッドで、ネットワークからリソースを取得するプロセスを開始し、レスポンスが利用できるようになったら満足するプロミスを返します。このプロミスはリクエストに対するレスポンスを表す {{domxref("Response")}} で解決します。プロミスは HTTP エラーでは拒否されず、ネットワークエラーでのみ拒否されます。 HTTP エラーをチェックするには、 then ハンドラーを使用する必要があります。
WindowOrWorkerGlobalScope は {{domxref("Window")}} と {{domxref("WorkerGlobalScope")}} の両方で実装されています。これはつまり fetch() メソッドはあなたがリソースを取得したいと思うような大部分コンテキストで使用可能ということです。
{{domxref("WindowOrWorkerGlobalScope.fetch","fetch()")}} のプロミスはネットワークエラーが発生した場合 (すなわち普通はパーミッション問題などがあったとき) のみ拒否されます。 {{domxref("WindowOrWorkerGlobalScope.fetch","fetch()")}} のプロミスは HTTP エラー (404 など) では拒否されません。代わりに、 then() ハンドラーで {{domxref("Response.ok")}} や {{domxref("Response.status")}} プロパティをチェックする必要があります。
fetch() メソッドは取得するリソースのディレクティブではなく Content Security Policy の connect-src ディレクティブによって制御されます。
注: fetch() メソッドの引数は {{domxref("Request.Request","Request()")}} コンストラクターと全く同じです。
const fetchResponsePromise = fetch(resource [, init])
resourceblob: と data: を受け入れます。init {{optional_inline}}リクエストに適用したいカスタム設定を含むオブジェクト。可能なオプションは以下の通りです。
methodGET、POST など。なお、 {{httpheader("Origin")}} ヘッダーは {{HTTPMethod("HEAD")}} または {{HTTPMethod("GET")}} メソッドの読み取りリクエストでは設定されません。headersbodyGET や HEAD の場合使用できないので注意してください。modecors, no-cors, same-origincredentialsomit, same-origin, include です。現在のドメインの Cookie を自動で送るためにはこのオプションを指定する必要があります。 Chrome 50 から、このプロパティは{{domxref("FederatedCredential")}} インスタンスや {{domxref("PasswordCredential")}} インスタンスを受け付けるようになりました。cacheredirectfollow (自動でリダイレクトに従う)、 error (リダイレクトが起こった場合エラーを伴って中止する)、 manual (手動でリダイレクトを処理する)。Chrome の既定値は follow です (バージョン 47 より前の既定値は manual でした)。referrerabout:client、空文字列のいずれかを取ることができます。referrerPolicyno-referrer, no-referrer-when-downgrade, same-origin, origin, strict-origin, origin-when-cross-origin, strict-origin-when-cross-origin, or unsafe-url のいずれかです。integritysha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=)。keepalivekeepalive オプションはページより長生きするリクエストを許可するのに使われます。keepalive フラグつきの Fetch は{{domxref("Navigator.sendBeacon()")}} API の置き換えです。signal{{domxref("Promise")}} で、 {{domxref("Response")}} オブジェクトに解決します。
AbortErrorTypeErrorFetch Request example リポジトリ (デモ: Fetch Request live) では {{domxref("Request")}} オブジェクトを関連するコンストラクターを使って作成しています。その後 fetch() を呼んで取得しています。画像を fetch している時から適切な MIME タイプを与えるために response の {{domxref("Body.blob")}} を実行し、適切に処理されます。そして ObjectURL を作成し {{htmlelement("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);
| 仕様書 | 状態 | 備考 |
|---|---|---|
| {{SpecName('Fetch','#fetch-method','fetch()')}} | {{Spec2('Fetch')}} | 最新の仕様では WindowOrWorkerGlobalScope の中で部分的に定義。 |
| {{SpecName('Fetch','#dom-global-fetch','fetch()')}} | {{Spec2('Fetch')}} | 初回定義 |
| {{SpecName('Credential Management')}} | {{Spec2('Credential Management')}} | {{domxref("FederatedCredential")}} または {{domxref("PasswordCredential")}} のインスタンスを init.credentials の値として追加。 |
{{Compat("api.WindowOrWorkerGlobalScope.fetch")}}