フェッチ（Fetch）
Fetch API
fetch(url, options)
url に対して HTTP リクエストを発行します。
async function getRequest(url) {
try {
const response = await fetch(url);
if (!response.ok) throw new Error(`ERROR: ${response.status}`);
const text = await response.text();
console.log(text);
} catch (err) {
console.error("fetch failed:", err);
}
}
送信オプション
options.method
HTTP メソッドを GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS のいずれかでを指定します。
fetch(url, {
method: "POST"
});
options.headers
HTTP ヘッダーを指定します。
fetch(url, {
headers: { "Content-Type": "text/plain" }
});
options.body
リクエストボディを指定します。GET や HEAD メソッドには body を指定することはできません。POST データを URL エンコード形式で送信するには下記の様にします。Content-Type は自動的に application/x-www-form-urlencoded となります。
fetch(url, {
method: "POST",
body: new URLSearchParams({ foo: "FOO", baa: "BAA" })
});
もしくは、下記の様に記述することもできます。
const form = new FormData();
form.append("foo", "FOO");
form.append("baa", "BAA");
fetch(url, {
method: "POST",
body: form,
});
ファイルを URL エンコード形式の POST データに混ぜてアップロードするには次のようにします。
const form = new FormData();
const input = document.getElementById("file1");
form.append("file1", input.files[0]);
fetch(url, {
method: "POST",
body: form,
});
JSON データを送信するには下記の様にします。Content-Type に application/json を指定する必要があります。
fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ foo: "FOO", baa: "BAA" })
});
options.redirect
redirect はリダイレクト方式を指定します。デフォルトは "follow" です。"manual" はマニュアルでリダイレクトを追従できるかのように見えますが、status に 0 が返却され、headers 情報も参照できず、リダイレクトが発生したことしか検出できない仕様となっています。
fetch(url, { redirect: mode })
fetch(url, { redirect: "follow" }) // リダイレクトに自動追従する
fetch(url, { redirect: "error" }) // リダイレクトが発生するとエラーとする
fetch(url, { redirect: "manual" }) // リダイレクトをマニュアルで...？
options.credentials
credentials は送信時に Cookie 情報、TLS クライアント証明書、認証ヘッダーなどの資格情報を送信するか否かを指定します。デフォルトは same-origin です。
fetch(url, { credentials: mode })
fetch(url, { credentials: "same-origin" }) // 同一オリジンの場合に送信する
fetch(url, { credentials: "omit" }) // 送信しない
fetch(url, { credentials: "include" }) // 別オリジンでも送信する
options.mode
mode はオリジン間リクエストの動作を指定します。デフォルトは cors です。
fetch(url, { mode: mode })
fetch(url, { mode: "cors" }) // CORS に従う
fetch(url, { mode: "same-origin" }) // 異なるオリジンへのアクセスを拒否
fetch(url, { mode: "no-cors" }) // CORS を無視してアクセスする(下記参照)
fetch(url, { mode: "navigate" }) // HTML文書間の移動の場合(通常は使用しない特殊値)
no-cors は GET, POST, HEAD でしか使用できず、レスポンスも参照できませんが、他オリジンへのビーコン送信や、画像のプリフェッチなどの目的で使用されることがあります。
options.cache
cache にはキャッシュ方式を指定します。デフォルトは default です。
fetch(url, { cache: mode })
fetch(url, { cache: "default" }) // デフォルトのキャッシュ方式
fetch(url, { cache: "no-store" }) // キャッシュを参照せず、格納しない
fetch(url, { cache: "reload" }) // キャッシュを参照せず、格納する
fetch(url, { cache: "force-cache" }) // キャッシュを参照し、格納する
fetch(url, { cache: "only-if-cached" }) // キャッシュを参照し、キャッシュされていなければエラー
fetch(url, { cache: "no-cache" }) // キャッシュの方が新しければ参照し、格納する
options.referrer
referrer は Referer ヘッダーに記述するアクセス元 URL 情報を指定します。デフォルトは about:client です。
fetch(url, { referrer: str })
fetch(url, { redirect: "about:client" }) // 現在の URL を送信
fetch(url, { redirect: "" }) // Referer ヘッダーを送信しない
fetch(url, { redirect: "/any/path" }) // 任意のパスを指定
options.referrerPolicy
referrerPolicy は Referer ヘッダーの送信ポリシーを制御します。詳細は Referrer-Policy ヘッダーを参照してください。
fetch(url, { referrerPolicy: policy })
options.priority
priority はリクエストの優先度を指定します。デフォルトは auto です。まだ試験的機能のようです。
fetch(url, { priority: level })
fetch(url, { priority: "auto" }) // 優先度を自動的に決めます
fetch(url, { priority: "low" }) // 低優先度とします
fetch(url, { priority: "high" }) // 高優先度とします
レスポンス
response.ok
HTTP リクエストが成功したか否かを返します。4xx や 5xx のエラーが発生している場合は false となります。
const response = await fetch(url);
if (!response.ok) console.log("ERROR");
response.status
HTTP レスポンスコードを返します。
const response = await fetch(url);
console.log(response.status); // 200 など
response.statusText
HTTP レスポンスコードに応じたテキスト (Not Found など) を返します。
const response = await fetch(url);
console.log(response.statusText); // Not Found など
response.text()
レスポンステキストを取得するための Promise を返します。
const response = await fetch(url); const text = await response.text();
response.json()
レスポンスを JSON 形式で取得するための Promise を返します。
const response = await fetch(url); const data = await response.json();
response.body
レスポンスボディを読み込むための ReadableStream オブジェクトを返します。例えば、Node.js で巨大なファイルをダウンロードしながらファイルに逐次書込みするには下記の様なコードを使用します。
import fs from 'node:fs';
import { Writable } from 'node:stream';
const response = await fetch("https://example.com/bigfile.zip");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const writable = Writable.toWeb(fs.createWriteStream('bigfile.zip'));
await response.body.pipeTo(writable);
response.bodyUsed
body が未使用であれば false を、使用済であれば true を返します。
const response = await fetch(url);
console.log(response.bodyUsed); // false
response.blob()
レスポンスボディを Blob 形式で返します。例えば、画像ファイルを読み込み、<img> 要素に埋め込むには次のようにします。
const response = await fetch("https://example.com/image/example.png");
const blob = await response.blob();
document.getElementById("img1").src = URL.createObjectURL(blob);
response.headers
レスポンスヘッダー情報を返します。
console.log(response.headers.get("Content-Type"));
response.headers.forEach((value, key) => {
console.log(`${key}: ${value}`);
});
response.redirected
リダイレクトが発生していれば true、発生していなければ false を返します。
const response = await fetch(url);
console.log(response.redirected); // true or false
response.url
リクエストした URL を返します。
const response = await fetch(url); console.log(response.url);
response.type
レスポンスのタイプを下記のいずれかで返します。
- basic：基本的な応答。
- cors：CORS リクエストに対する応答。
- error：ネットワークエラー。実際には Promise エラーとなるためこの値になることは稀。
- opaque：
mode: "no-cors"リクエストのレスポンス。statusは0となりヘッダーやボディは見えない。 - opaqueredirect：
redirect: "manual"リクエストのレスポンス。statusは0となりヘッダーやボディは見えない。
const response = await fetch(url); console.log(response.type);