Window: fetch() メソッド
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2017.
fetch()
は Window
インターフェイスのメソッドで、ネットワークからリソースを取得するプロセスを開始し、レスポンスが利用できるようになったら履行されるプロミスを返します。
このプロミスは、そのリクエストに対するレスポンスを表す Response
で解決します。
fetch()
のプロミスは、ネットワークエラーが発生した場合(普通は権限の問題がaったときなど)のみ拒否されます。
fetch()
のプロミスは、サーバーがエラーを示す HTTP ステータスコード(404
、504
など)を返しても拒否されません。
代わりに、 then()
ハンドラーで Response.ok
や Response.status
プロパティをチェックする必要があります。
fetch()
メソッドは取得するリソースのディレクティブではなく、コンテンツセキュリティポリシーの connect-src
ディレクティブによって制御されます。
メモ: fetch()
メソッドの引数は Request()
コンストラクターと全く同じです。
構文
fetch(resource)
fetch(resource, options)
引数
resource
-
取得したいリソースを定義します。以下のどちらかが使用できます。
- 文字列または文字列化できるその他のオブジェクト(
URL
オブジェクトを含む)。取得したいリソースの直接の URL を含む文字列です。この URL は、文書内のbaseURI
、ワーカーコンテキストではWorkerGlobalScope.location
となります。 Request
オブジェクト。
- 文字列または文字列化できるその他のオブジェクト(
options
省略可-
リクエストに適用する独自の設定を含む
RequestInit
オブジェクトです。
返値
例外
AbortError
DOMException
-
AbortController
のabort()
メソッドの呼び出しによりリクエストが中止された。 NotAllowedError
DOMException
-
トピック API を使用することが、権限ポリシーの
browsing-topics
によって特別に禁止されており、そしてfetch()
リクエストがbrowsingTopics: true
で行われたときに発生します。 TypeError
-
以下の理由で発生する可能性があります。
理由 | 失敗する例 |
---|---|
権限ポリシーによるブロック | Attribution Reporting API の使用は、attribution-reporting Permissions-Policy で、fetch() リクエストが attributionReporting を指定して行われました。 |
ヘッダー名が無効である。 |
// "C ontent-Type" に空白がある const headers = { 'C ontent-Type': 'text/xml', 'Breaking-Bad': '<3', }; fetch('https://example.com/', { headers }); |
ヘッダーの値が無効である。ヘッダーオブジェクトは正確に 2 つの要素を含まなければならない。 |
const headers = [ ['Content-Type', 'text/html', 'extra'], ['Accept'], ]; fetch('https://example.com/', { headers }); |
URL またはスキームが無効であるか、フェッチが対応していないスキームを使用しているか、または特定のリクエストモードに対応していないスキームを使用している。 |
fetch('blob://example.com/', { mode: 'cors' }); |
URL に資格情報が入っている。 |
fetch('https://user:password@example.com/'); |
リファラー URL が不正である。 |
fetch('https://example.com/', { referrer: './abc\u0000df' }); |
モードが不正(navigate や websocket )。 |
fetch('https://example.com/', { mode: 'navigate' }); |
リクエストキャッシュモードが "only-if-cached" で、かつリクエストモードが "same-origin" 以外の場合。 |
fetch('https://example.com/', { cache: 'only-if-cached', mode: 'no-cors', }); |
リクエストメソッドが無効な名前トークンである場合、または禁止されたヘッダー('CONNECT' , 'TRACE' , 'TRACK' )の 1 つである場合。 |
fetch('https://example.com/', { method: 'CONNECT' }); |
リクエストモードが "no-cors" であり、リクエストメソッドが CORS セーフリストに掲載されているメソッド('GET' , 'HEAD' , 'POST' )でない場合。 |
fetch('https://example.com/', { method: 'CONNECT', mode: 'no-cors', }); |
リクエストメソッドが 'GET' または 'HEAD' で、本体が null でないか、 undefined でない場合。 |
fetch('https://example.com/', { method: 'GET', body: new FormData(), }); |
fetch がネットワークエラーを発生した場合。 |
例
Fetch Request の例(Fetch Request のライブ版を参照)では、 Request
オブジェクトを関連するコンストラクターで作成しています。その後で fetch()
を呼び出して取得しています。画像を読み取っているため、レスポンスで Response.blob()
を実行して正しい MIME タイプを指定して正しく扱われるようにし、オブジェクト URL を作成して <img>
要素に追加して表示させています。
const myImage = document.querySelector("img");
const myRequest = new Request("flowers.jpg");
window
.fetch(myRequest)
.then((response) => {
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`);
}
return response.blob();
})
.then((response) => {
myImage.src = URL.createObjectURL(response);
});
Fetch Request with init の例(Fetch Request init のライブ版)では上記の内容に加えて、fetch()
を呼び出すとき、初期化オブジェクト init
を渡しています。
この場合、Cache-Control
値を設定することで、どのようなキャッシュレスポンスであれば問題ないかを示すことができます。
const myImage = document.querySelector("img");
const reqHeaders = new Headers();
// キャッシュされたレスポンスは、それが 1 週間以上前のものでなければ問題ない
reqHeaders.set("Cache-Control", "max-age=604800");
const options = {
headers: reqHeaders,
};
// init をヘッダーと一緒に "options" オブジェクトとして渡す
const req = new Request("flowers.jpg", options);
fetch(req).then((response) => {
// ...
});
同様に init
オブジェクトを Request
コンストラクターに渡しても、同じ効果が得られます。
const req = new Request("flowers.jpg", options);
init
の headers
でオブジェクトリテラルを使用することもできます。
const options = {
headers: {
"Cache-Control": "max-age=60480",
},
};
const req = new Request("flowers.jpg", options);
仕様書
Specification |
---|
Fetch Standard # fetch-method |
ブラウザーの互換性
BCD tables only load in the browser