JavaScript
PR

JavaScriptのfetchでAPIを呼ぶ|POST・エラー処理・タイムアウト

JavaScriptのfetchでAPIを呼ぶ|POST・エラー処理・タイムアウト
hr
記事内に商品プロモーションを含む場合があります

Web API からデータを取ってくる JavaScript の関数が fetch です。書き方は短いのですが、「404 なのに catch に来ない」「response.json() でエラーになる」「別のポートの API を呼んだら失敗した」など、つまずきやすい点がいくつもあります。

この記事では、自分の PC だけで動く練習用 API サーバーを Python で立て、GET・POST、エラーの見分け方、タイムアウト、CORS エラーまでを実行結果つきで解説します。結果は Microsoft Edge 156(156.0.4314.42)のヘッドレスモードで確かめたもので、時間は環境で少し変わります。Promise と await の基本は「JavaScriptの非同期処理入門」を参照してください。

fetch とは:API に HTTP リクエストを送る関数

fetch(URL, オプション) は、ブラウザーから HTTP リクエストを送り、結果を Promise(あとで結果を渡す約束)で返す関数です。メソッドやステータスコードの意味は「REST APIとは?」を参照してください。

準備:練習用の API サーバーを自分の PC で動かす

練習には、Python の標準ライブラリだけで、わざと 404・500・遅い応答・壊れた JSON を返すサーバーを作ります。作業用のフォルダー(例:fetch-practice)に、次の内容を server.py という名前の UTF-8 で保存します。

import json
import threading
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

TODOS = [
    {"id": 1, "title": "牛乳を買う", "done": False},
    {"id": 2, "title": "fetch を覚える", "done": True},
]
PAGE = "<!DOCTYPE html><meta charset='utf-8'><title>fetch practice</title><h1>fetch practice</h1>"


class Handler(BaseHTTPRequestHandler):
    def send(self, status, body, content_type="application/json; charset=utf-8", delay=0):
        if not isinstance(body, str):
            body = json.dumps(body, ensure_ascii=False)
        data = body.encode("utf-8")
        self.send_response(status)
        self.send_header("Content-Type", content_type)
        self.send_header("Content-Length", str(len(data)))
        self.end_headers()
        self.wfile.flush()
        time.sleep(delay)  # 本文だけ遅らせる
        self.wfile.write(data)

    def do_GET(self):
        print(self.server.server_port, "GET", self.path, "Origin:", self.headers.get("Origin"), flush=True)
        if self.path == "/":
            self.send(200, PAGE, "text/html; charset=utf-8")
        elif self.path == "/api/todos":
            self.send(200, TODOS)
        elif self.path == "/api/error":
            self.send(500, {"error": "サーバー内部のエラー"})
        elif self.path == "/api/slow":
            time.sleep(5)  # わざと 5 秒待ってから返す
            try:
                self.send(200, {"message": "5 秒かかりました"})
            except ConnectionError:
                print("返そうとしたら、接続はもう切られていました", flush=True)
        elif self.path == "/api/slow-body":
            self.send(200, TODOS, delay=2)  # ヘッダーはすぐ、本文は 2 秒後
        elif self.path == "/api/broken":
            self.send(200, "<!DOCTYPE html><h1>メンテナンス中</h1>", "text/html; charset=utf-8")
        else:
            self.send(404, {"error": "見つかりません"})

    def do_POST(self):
        content_type = self.headers.get("Content-Type", "")
        length = int(self.headers.get("Content-Length", 0))
        raw = self.rfile.read(length)
        print(self.server.server_port, "POST", self.path, "Content-Type:", content_type,
              "本文:", raw.decode("utf-8", "replace"), flush=True)
        if self.path != "/api/todos":
            self.send(404, {"error": "見つかりません"})
        elif not content_type.startswith("application/json"):
            self.send(415, {"error": f"Content-Type は application/json にしてください(受け取ったのは {content_type})"})
        else:
            try:
                item = json.loads(raw)
            except json.JSONDecodeError:
                self.send(400, {"error": "JSON として読めません"})
                return
            created = {"id": len(TODOS) + 1, "title": item.get("title"), "done": False}
            self.send(201, created)

    def log_message(self, format, *args):
        pass  # 標準のアクセスログは出さない


if __name__ == "__main__":
    # 8152 は CORS を試すための「別オリジン」(ポートが違うと別オリジン)
    other = ThreadingHTTPServer(("127.0.0.1", 8152), Handler)
    threading.Thread(target=other.serve_forever, daemon=True).start()
    main = ThreadingHTTPServer(("127.0.0.1", 8151), Handler)
    print("http://127.0.0.1:8151/ で待ち受け中(Ctrl+C で終了)", flush=True)
    try:
        main.serve_forever()
    except KeyboardInterrupt:
        print("終了しました")
パス返すもの
/api/todosGET:ToDo の配列(JSON)。POST:JSON を受け取って 201
/api/error500(サーバー内部のエラー)
/api/slow5 秒待ってから 200
/api/slow-bodyヘッダーはすぐ、本文は 2 秒後
/api/broken200 だが中身は HTML(JSON ではない)
それ以外404(見つかりません)

127.0.0.1 で待ち受けるので、ほかの PC からはつながりません。ポート 8152 は CORS を試すための「別のサーバー」役です。

  1. エクスプローラーで作業用フォルダーを開き、アドレス欄に powershell と入力して Enter キーを押します。
  2. 開いた PowerShell で次のコマンドを実行します。「http://127.0.0.1:8151/ で待ち受け中(Ctrl+C で終了)」と表示されれば起動しています。
py server.py
  1. Edge か Chrome のアドレス欄に次の URL を入力して開きます。「fetch practice」と表示されます。
http://127.0.0.1:8151/
  1. F12 キーを押し、開いた開発者ツールの上部の「Console(コンソール)」タブを選びます。
  2. この記事のコードを貼り付けて Enter キーを押します。次のコードを試す前に F5 キーで再読み込みすると、変数名がぶつかるエラーを防げます。

fetch("/api/todos") のように「/」で始まる URL は今開いているページと同じサーバーを指すので、必ず http://127.0.0.1:8151/ を開いたタブで試してください。初めて貼り付けるときに警告が出ることがありますが、知らない人から教えられたコードは絶対に貼り付けないでください。

基本:GET で JSON を受け取る(await は 2 回)

const response = await fetch("/api/todos");
console.log(response.status, response.ok);
console.log(response.headers.get("Content-Type"));
const todos = await response.json();
console.log(todos.length, todos[0].title);
200 true
application/json; charset=utf-8
2 牛乳を買う

ポイントは await が 2 回あることです(コンソールでは関数の外でも await が使えます)。1 回目の await fetch(…) で受け取るのは、ステータスコードやヘッダーの入った Response オブジェクトで、データそのものではありません。2 回目の await response.json() で本文を読み、JSON を JavaScript の配列やオブジェクトに変換します。

MDN の「Using the Fetch API」には、ブラウザーがステータスとヘッダーを受け取った時点で、本文を受け取る前でも fetch の Promise は Response で成功する、と書かれています。ヘッダーはすぐ、本文は 2 秒後に返す /api/slow-body で確かめます。

const start = performance.now();
const response = await fetch("/api/slow-body");
console.log(`fetch が完了:${((performance.now() - start) / 1000).toFixed(2)} 秒`, response.status);
const todos = await response.json();
console.log(`json() が完了:${((performance.now() - start) / 1000).toFixed(2)} 秒`, todos.length);
fetch が完了:0.00 秒 200
json() が完了:2.00 秒 2
JavaScript とサーバーのやり取りを上から下へ時間順に描いた図。JavaScript が GET /api/slow-body を送り、サーバーがまずステータス行とヘッダーを返す。この時点の 0.00 秒で await fetch が終わり、status や ok や headers を持つ Response が手に入る。本文の JSON の文字列は 2 秒後に届き、その 2.00 秒の時点で await response.json が終わって JavaScript の配列やオブジェクトになる。
図 1:fetch はヘッダーが届いた時点で Response を返し、本文は json() で読む

本文は json() のほか text()(文字列のまま)でも読め、どちらも await が必要です。受け取った JSON が長くて読みにくいときは、text() の結果を「JSON整形ツール」に貼ると整えて表示できます。

Response のよく使うプロパティは、status(ステータスコードの数値)、statusText("OK" などのメッセージ)、ok(MDN の説明では、ステータスが 200〜299 なら true)、headers(get("名前") でヘッダーを読む)です。ヘッダーの種類は「HTTPヘッダーの読み方」で解説しています。

落とし穴:404 や 500 では catch に来ない

fetch で一番多い勘違いがこれです。存在しないパス(404)と、サーバーのエラー(500)を try/catch 付きで呼んでみます。

for (const url of ["/api/todos", "/api/nothing", "/api/error"]) {
  try {
    const response = await fetch(url);
    console.log(url, response.status, response.statusText, response.ok);
  } catch (error) {
    console.log(url, "catch に来た:", error.message);
  }
}
/api/todos 200 OK true
/api/nothing 404 Not Found false
/api/error 500 Internal Server Error false

404 も 500 も catch に来ず、普通に Response が返りました。MDN の fetch のページにも「サーバーがエラーを示すステータスコード(404、504 など)で応答しても、fetch の Promise は reject(失敗)しない。Response.ok や Response.status を確かめる必要がある」と書かれています。fetch にとっては「サーバーから返事が来た」ので成功なのです。

ok を確かめてから JSON を返す関数を作る

毎回 ok を確かめるのは忘れやすいので、関数にまとめておくと安全です。ok が false なら自分で throw して、呼ぶ側の catch に届くようにします。

async function getJSON(url) {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP ${response.status} ${response.statusText}(${url})`);
  }
  return response.json();
}

try {
  const todos = await getJSON("/api/todos");
  console.log("件数:", todos.length);
  const missing = await getJSON("/api/nothing");
  console.log("ここは表示されない", missing);
} catch (error) {
  console.log("エラー:", error.message);
}
件数: 2
エラー: HTTP 404 Not Found(/api/nothing)

エラーのときも本文は読めます。/api/nothing の本文を json() で読むと error は「見つかりません」で、API によってはここに理由が入っています。throw の使い方は「JavaScriptのエラー処理入門」、ステータスコードの意味は「HTTPステータスコード検索」で調べられます。

catch に来るのは通信できなかったとき(TypeError: Failed to fetch)

では、どんなときに reject されるのでしょうか。サーバーを止めて確かめます。PowerShell の画面で Ctrl+C キーを押してサーバーを止め、ページを再読み込みせずに、同じタブのコンソールで次を実行します。

try {
  const res = await fetch("/api/todos");
  console.log(res.status);
} catch (error) {
  console.log(error.name + ": " + error.message, error instanceof TypeError);
}
TypeError: Failed to fetch true

今度は catch に来て、TypeError: Failed to fetch(取得に失敗した)になりました。MDN では TypeError になる理由として、URL が正しくない、ネットワークのエラーなどが挙げられています(文言は Edge のもので、ブラウザーにより違うことがあります)。確かめたら py server.py でサーバーを起動し直します。

状況fetch の結果見分け方
200 番台成功(Response)response.ok が true
404・500 など成功(Response)response.ok が false
サーバーが止まっている・ネットワークがない失敗(TypeError)catch に来る
CORS で許可されていない失敗(TypeError)catch に来る(後述)
AbortController・タイムアウトで中止失敗(AbortError・TimeoutError)error.name(後述)

POST で JSON を送る

データを送るときは、第 2 引数のオプションに method・headers・body を指定します。

const response = await fetch("/api/todos", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ title: "記事を書く" }),
});
console.log(response.status, response.statusText);
const created = await response.json();
console.log(created.id, created.title, created.done);
201 Created
3 記事を書く false
  • method:省略すると GET。送るときは "POST" など
  • headers:本文の形式を Content-Type でサーバーに伝える
  • body:送る本文。オブジェクトは JSON.stringify で JSON の文字列にしてから渡す(詳しくは「JavaScriptのJSON.parseとstringify」)

Content-Type を付け忘れると 415 になる

上のコードから headers の行だけを消して送ると、結果は次のようになりました。

415 Unsupported Media Type
Content-Type は application/json にしてください(受け取ったのは text/plain;charset=UTF-8)

本文が文字列のとき、fetch は Content-Type を text/plain;charset=UTF-8 にして送ります(サーバー側の表示で確認)。中身は JSON でも、サーバーは「JSON ではない」と判断して 415 を返しました。「HTTPヘッダーの読み方」の実例 2(curl で付け忘れた例)と同じ失敗です。400 を返すサーバーもあります。

JSON.stringify を忘れると「[object Object]」が届く

body: { title: "記事を書く" } のようにオブジェクトのまま渡すと、エラーにはならずに送信され、サーバーには次のように届きました(PowerShell の画面の表示)。

8151 POST /api/todos Content-Type: application/json 本文: [object Object]

MDN にあるとおり、オブジェクトは toString() で文字列にされるためです。サーバーは 400(JSON として読めません)を返しました。

本文は 1 回しか読めない(body stream already read)

デバッグのつもりで json() を 2 回呼ぶと、2 回目でエラーになります。

const response = await fetch("/api/todos");
console.log((await response.json()).length);
try {
  console.log(await response.json());
} catch (error) {
  console.log(error.name + ": " + error.message);
}
2
TypeError: Failed to execute 'json' on 'Response': body stream already read

本文はストリーム(流れてくるデータ)なので、一度読むと読めません(response.bodyUsed が false から true になります)。2 回読みたいときは、MDN にあるとおり読む前に response.clone() で複製するか、json() の結果を変数に入れて使い回します。

JSON でないものが返ると SyntaxError

メンテナンス中のページなど、200 なのに HTML が返る /api/broken を json() で読んでみます。

const response = await fetch("/api/broken");
console.log(response.status, response.ok, response.headers.get("Content-Type"));
try {
  const data = await response.json();
} catch (error) {
  console.log(error.name + ": " + error.message);
}
200 true text/html; charset=utf-8
SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON

ok は true なのに、json() が SyntaxError で失敗しました。「Unexpected token ‘<‘」は、受け取ったのが HTML だという合図です(URL の間違い、ログイン画面が返った など)。Content-Type が application/json で始まるかを確かめてから json() を呼び、原因は text() で中身を見て調べます。

タイムアウト:AbortSignal.timeout と AbortController

fetch には「何秒で諦める」という設定が初めからありません。サーバーが返事をしないと、ずっと待ち続けます。制限時間を付けるには signal オプションに AbortSignal.timeout(ミリ秒) を渡します。5 秒かかる /api/slow を 2 秒で打ち切ります。

const start = performance.now();
try {
  const response = await fetch("/api/slow", { signal: AbortSignal.timeout(2000) });
  console.log(response.status);
} catch (error) {
  console.log(error.name, error.message);
}
console.log(`${((performance.now() - start) / 1000).toFixed(2)} 秒`);
TimeoutError signal timed out
2.00 秒

約 2 秒(実測 2.00 秒・2.02 秒)で、MDN の説明どおり TimeoutError になりました。

「キャンセル」ボタンなどで止めるときは AbortController を使います。new AbortController() の signal を fetch に渡し、1 秒後に abort() を呼ぶと、約 1 秒で AbortError(signal is aborted without reason)になりました。error.name が TimeoutError か AbortError かで、時間切れか自分で止めたかを区別できます。

注意したいのは、止まるのはブラウザー側の待ちだけということです。サーバーは 5 秒後に最後まで処理し、PowerShell に「返そうとしたら、接続はもう切られていました」と表示されました。POST がタイムアウトしてもサーバー側では登録が済んでいることがあり、すぐ再送すると二重登録のおそれがあります。

別のポートの API を呼ぶと CORS エラーになる

ポートが違うと、ブラウザーは別のサイト(別オリジン)として扱います。8151 のページから、8152 のサーバーを呼んでみます。

try {
  const response = await fetch("http://127.0.0.1:8152/api/todos");
  console.log(response.status);
} catch (error) {
  console.log(error.name + ": " + error.message);
}
TypeError: Failed to fetch

JavaScript に届くのはサーバー停止のときと同じ TypeError: Failed to fetch だけですが、コンソールには赤い字で次のメッセージが出ました。

Access to fetch at 'http://127.0.0.1:8152/api/todos' from origin 'http://127.0.0.1:8151' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

PowerShell には 8152 GET /api/todos Origin: http://127.0.0.1:8151 と表示され、リクエストはサーバーに届いています。返事に Access-Control-Allow-Origin ヘッダーがないので、ブラウザーが JavaScript に読ませなかったのです。直すのはサーバー側の設定で、仕組みは「CORSとは?」で解説しています。

XMLHttpRequest との違い

古いコードでは XMLHttpRequest(XHR)をよく見かけます。new XMLHttpRequest() を作って open("GET", "/api/todos")・send() し、load イベントで結果を受け取る書き方で、同じ API から同じ 2 件を受け取れました。

違いは、結果をイベントのコールバックで受け取るか(XHR)、Promise で受け取って await できるか(fetch)です。404 でも load イベントが来て status が 404 になり、エラーを自分で判断する点は同じでした。新しく書くなら fetch で十分です。

API キーをフロントエンドの JavaScript に書かない

headers: { "Authorization": "Bearer 本物のキー" } のように、API キーをブラウザーで動く JavaScript に書いてはいけません。ブラウザーで動くコードと送ったリクエストは、開発者ツールで誰でも見られるからです。抜き取られたキーで API を使われ、料金を請求されるおそれがあります。

秘密のキーが必要な API は、自分のサーバー側から呼び、ブラウザーは自分のサーバーにだけ fetch します。キーはサーバーの環境変数などに置きます(「.envと環境変数で秘密情報を守る」参照)。

よくある質問

Python からも同じ API を呼べますか?

呼べます。CORS の制限はなく、urllib では 404 などで例外が出るなど、エラーの扱いが fetch と違います(「PythonでHTTPリクエストを送る方法」)。コマンドなら「curlコマンドの使い方」も参考になります。

まとめ

  • await fetch() で Response、await response.json() で中身。404・500 は catch に来ないので ok を確かめる
  • POST は method・Content-Type・JSON.stringify の 3 点セット
  • タイムアウトは AbortSignal.timeout()。API キーはフロントエンドに書かない

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました