Python
PR

PythonでHTTPリクエストを送る方法|urllibとrequestsの使い方と例外処理

PythonでHTTPリクエストを送る方法|urllibとrequestsの使い方と例外処理
hr
記事内に商品プロモーションを含む場合があります

Python で Web API からデータを取ったりフォームの内容を送ったりするには、HTTP リクエストを送ります。方法は大きく 2 つで、インストール不要の標準ライブラリ urllib.request と、短く書けて広く使われている外部ライブラリ requests です。

この記事では、自分の PC(127.0.0.1)で動かす練習用サーバーに両方から送り、GET とクエリパラメーター、フォームと JSON の POST、ヘッダー、ステータスコード、タイムアウト、例外処理、文字化け、Cookie を比べます。出力は Windows 11・PowerShell 5.1・Python 3.12.6・requests 2.34.2 で実行した結果です(2026 年 10 月)。他人のサービスに練習のリクエスト、特に POST を送らないようにしましょう。

urllib と requests の違い

項目urllib.requestrequests
インストール不要(標準ライブラリ)必要(pip install requests)
クエリパラメーターurllib.parse.urlencode で組み立てるparams= に辞書を渡す
POST の本文bytes に変換して data= に渡すdata=(フォーム)か json= に辞書を渡す
4xx・5xx が返ったとき自動で例外 HTTPError例外にならない。raise_for_status() で例外にする
タイムアウトの既定なし(socket の既定値 None)なし
Cookie の引き継ぎhttp.cookiejar と openerrequests.Session() を使う

Python の公式ドキュメント(urllib.request)も、より高水準なインターフェースとして Requests パッケージを推奨しています。インストールできない環境や依存を増やしたくない小さなスクリプトでは urllib、それ以外は requests と考えるとよいでしょう。

準備:練習用サーバーと requests のインストール

練習用サーバー(practice_server.py)

標準ライブラリだけで作った練習用サーバーです。作業用のフォルダーに practice_server.py(文字コードは UTF-8)として保存します。考え方は「REST APIとは?」の ToDo API と同じです。

# practice_server.py : HTTP リクエストの練習用サーバー(127.0.0.1 だけで待ち受ける)
import json
import os
import secrets
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import parse_qs, urlsplit

sessions = {}  # セッション ID → ユーザー名(メモリー上だけ)


class Handler(BaseHTTPRequestHandler):
    def send(self, status, data, ctype="application/json; charset=utf-8", cookie=None):
        body = data if isinstance(data, bytes) else json.dumps(data, ensure_ascii=False).encode("utf-8")
        self.send_response(status)
        if cookie:
            self.send_header("Set-Cookie", cookie)
        self.send_header("Content-Type", ctype)
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def do_GET(self):
        url = urlsplit(self.path)
        token = os.environ.get("PRACTICE_TOKEN")
        sid = self.headers.get("Cookie", "").removeprefix("sid=")
        if url.path == "/search":  # クエリパラメーターと User-Agent を返す
            self.send(200, {"query": parse_qs(url.query), "user_agent": self.headers["User-Agent"]})
        elif url.path == "/private" and token and self.headers["Authorization"] == f"Bearer {token}":
            self.send(200, {"message": "認証に成功しました"})
        elif url.path == "/private":
            self.send(401, {"error": "トークンが違います"})
        elif url.path == "/broken":  # わざと 500 を返す
            self.send(500, {"error": "サーバー内部のエラー"})
        elif url.path == "/slow":  # 10 秒たってから返す
            time.sleep(10)
            self.send(200, {"message": "遅れて返しました"})
        elif url.path == "/nocharset":  # charset を付けずに UTF-8 の日本語を返す
            self.send(200, "こんにちは".encode("utf-8"), "text/plain")
        elif url.path == "/me" and sid in sessions:  # Cookie でログイン中か調べる
            self.send(200, {"user": sessions[sid]})
        elif url.path == "/me":
            self.send(401, {"error": "ログインしていません"})
        else:
            self.send(404, {"error": "見つかりません"})

    def do_POST(self):
        length = int(self.headers.get("Content-Length") or 0)
        if length > 10_000:  # 大きすぎる本文は受け取らない
            return self.send(413, {"error": "本文が大きすぎます"})
        body = self.rfile.read(length).decode("utf-8", errors="replace")
        name = parse_qs(body).get("name", [""])[0]
        if self.path == "/echo":  # 受け取った Content-Type と本文を返す
            self.send(200, {"content_type": self.headers.get("Content-Type", ""), "body": body})
        elif self.path == "/login" and name:  # Cookie でセッション ID を渡す
            sid = secrets.token_hex(16)
            sessions[sid] = name
            self.send(200, {"message": "ログインしました"}, cookie=f"sid={sid}; HttpOnly; Path=/")
        elif self.path == "/login":
            self.send(400, {"error": "name が必要です"})
        else:
            self.send(404, {"error": "見つかりません"})


class Server(ThreadingHTTPServer):
    allow_reuse_address = False  # Windows で同じポートに二重に起動できてしまうのを防ぐ
    daemon_threads = True


if __name__ == "__main__":
    server = Server(("127.0.0.1", 8765), Handler)
    print("http://127.0.0.1:8765 で待ち受け中(Ctrl+C で終了)")
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        pass

/private で使うトークン(合言葉)は、コードに書かずに環境変数 PRACTICE_TOKEN から読みます。PowerShell で設定してから起動します(値は練習用の例)。

$env:PRACTICE_TOKEN = "practice-token-123"
py practice_server.py

「http://127.0.0.1:8765 で待ち受け中(Ctrl+C で終了)」と出たらこの画面は開いたままにし、以降は別の PowerShell の画面で作業します。待ち受けるのは自分の PC からしか接続できない 127.0.0.1 です。0.0.0.0 に変えたり公開したりしないでください。

requests を仮想環境に入れる

requests は外部のパッケージなので、作業用フォルダーに仮想環境を作って、その中に入れます。仮想環境については「Pythonの仮想環境venvの使い方」で詳しく解説しています。

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install requests

確認時点の PyPI の最新版は 2.34.2(2026 年 5 月 14 日公開、Python 3.10 以上)です。以降のスクリプトは、仮想環境を有効にした画面で python ファイル名.py として実行します。

GET:クエリパラメーターを付けて取得する

URL の「?」の後ろに付く q=python&page=2 のような部分を、クエリパラメーターと呼びます。日本語や空白はそのまま URL に入れられないので、%E5%85%A5 のような形(URL エンコード)に変換して送ります。

urllib の場合

import json
import urllib.parse
import urllib.request

params = urllib.parse.urlencode({"q": "python 入門", "page": 2})
url = "http://127.0.0.1:8765/search?" + params
print(url)

with urllib.request.urlopen(url, timeout=5) as res:
    print(res.status, res.headers["Content-Type"])
    data = json.loads(res.read().decode("utf-8"))
print(data)
http://127.0.0.1:8765/search?q=python+%E5%85%A5%E9%96%80&page=2
200 application/json; charset=utf-8
{'query': {'q': ['python 入門'], 'page': ['2']}, 'user_agent': 'Python-urllib/3.12'}

urlencode が空白を「+」に、「入門」を UTF-8 のバイト列の %E5%85%A5%E9%96%80 に変換しています。res.read() で受け取れるのは bytes(バイト列)なので、decode("utf-8") で文字列にしてから json.loads で辞書に変換します。JSON の扱いは「PythonでJSONを扱う方法」で詳しく解説しています。

requests の場合

import requests

res = requests.get("http://127.0.0.1:8765/search",
                   params={"q": "python 入門", "page": 2}, timeout=5)
print(res.url)
print(res.status_code, res.headers["content-type"])
print(res.json())
http://127.0.0.1:8765/search?q=python+%E5%85%A5%E9%96%80&page=2
200 application/json; charset=utf-8
{'query': {'q': ['python 入門'], 'page': ['2']}, 'user_agent': 'python-requests/2.34.2'}

params= に辞書を渡すだけで同じ URL になり、res.json() で本文を辞書にできます。ヘッダー名は大文字・小文字を区別しません。サーバーに届いた User-Agent(送り手のプログラム名)は、urllib では Python-urllib/3.12、requests では python-requests/2.34.2 でした。

POST:フォームと JSON を送る

POST の本文の形式は主に 2 つです。HTML のフォームと同じ name=hr&lang=ja の形(Content-Type は application/x-www-form-urlencoded)と、JSON(application/json)です。どちらを受け付けるかは API の仕様書で確認します。

urllib の場合

import json
import urllib.parse
import urllib.request

URL = "http://127.0.0.1:8765/echo"

# フォームの形式で送る
form = urllib.parse.urlencode({"name": "hr", "lang": "ja"}).encode("ascii")
with urllib.request.urlopen(URL, data=form, timeout=5) as res:
    print(json.loads(res.read().decode("utf-8")))

# JSON で送る
body = json.dumps({"title": "牛乳を買う"}).encode("utf-8")
req = urllib.request.Request(URL, data=body, method="POST",
                             headers={"Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=5) as res:
    print(json.loads(res.read().decode("utf-8")))
{'content_type': 'application/x-www-form-urlencoded', 'body': 'name=hr&lang=ja'}
{'content_type': 'application/json', 'body': '{"title": "\\u725b\\u4e73\\u3092\\u8cb7\\u3046"}'}

urllib では、data= に渡す本文を必ず bytes にします。data を渡すと POST になり、Content-Type を指定しなければ application/x-www-form-urlencoded が自動で付きます(公式ドキュメントの記述どおり)。JSON のときは Content-Type を自分で指定します。\u725b は json.dumps が日本語を変換した形で、読み込めば「牛乳を買う」に戻ります。

requests の場合

import requests

URL = "http://127.0.0.1:8765/echo"

res = requests.post(URL, data={"name": "hr", "lang": "ja"}, timeout=5)  # フォーム
print(res.json())

res = requests.post(URL, json={"title": "牛乳を買う"}, timeout=5)  # JSON
print(res.json())

出力は urllib と同じ 2 行でした。data= に辞書を渡すとフォームの形式に、json= に辞書を渡すと JSON に変換され、Content-Type も自動で付きます。送る JSON や返ってきた JSON が読みにくいときは、「JSON整形ツール」に貼ると整形と構文チェックができます。

ヘッダーを付ける:認証トークンは環境変数から

多くの API では、API キーやアクセストークンを Authorization ヘッダーに付けて送ります。トークンはパスワードと同じで、ソースコードに直接書かず、環境変数から読み込みます。コードに書くと、Git にコミットしたときに履歴に残ってしまうからです。くわしくは「.envと環境変数で秘密情報を守る」を参照してください。

import os
import requests

token = os.environ["PRACTICE_TOKEN"]  # トークンはコードに書かず、環境変数から読む
res = requests.get("http://127.0.0.1:8765/private",
                   headers={"Authorization": f"Bearer {token}"}, timeout=5)
print(res.status_code, res.json())

クライアントの画面でも $env:PRACTICE_TOKEN = "practice-token-123" を実行してから動かすと 200 {'message': '認証に成功しました'}、違う値にすると 401 {'error': 'トークンが違います'} になりました。設定し忘れると KeyError: 'PRACTICE_TOKEN' で止まるので、トークンなしで送ってしまうことも防げます。urllib では urllib.request.Request(url, headers={...}) にヘッダーを渡します(同じく 200 を確認)。

ステータスコードと例外処理

失敗には 2 種類あります。404 や 500 などのエラーが返ってきた場合と、返事が来なかった場合(接続の拒否、ホスト名が見つからない、時間切れ)です。ステータスコードの意味は「HTTPステータスコード検索」で調べられます。

urllib:HTTPError と URLError

urllib は、4xx・5xx が返ると urllib.error.HTTPError、接続できないと urllib.error.URLError を出します。HTTPError は URLError の子クラスなので、HTTPError の except を先に書きます。次のコードでは、500 を返す URL、何も待ち受けていないポート 8766、存在しないホスト名(.invalid は存在しないと決まっている名前)に送ります。

import json
import urllib.error
import urllib.request

for url in ["http://127.0.0.1:8765/broken",
            "http://127.0.0.1:8766/",
            "http://no-such-host.invalid/"]:
    try:
        with urllib.request.urlopen(url, timeout=5) as res:
            print(res.status)
    except urllib.error.HTTPError as e:  # 4xx・5xx(サーバーから返事はあった)
        print("HTTPError:", e.code, json.loads(e.read().decode("utf-8")))
    except urllib.error.URLError as e:  # 接続できない・名前が引けないなど
        print("URLError:", e.reason)
HTTPError: 500 {'error': 'サーバー内部のエラー'}
URLError: [WinError 10061] 対象のコンピューターによって拒否されたため、接続できませんでした。
URLError: [Errno 11001] getaddrinfo failed

HTTPError からは e.code でステータスコードを、e.read() でエラーの本文(理由が入っていることが多い)を取り出せます。

requests:status_code と raise_for_status

requests は、404 や 500 が返っても例外を出しません。res.status_code を自分で確かめるか、res.raise_for_status() を呼んで 4xx・5xx のときだけ requests.exceptions.HTTPError を出させます。500 のレスポンスで呼ぶと、例外のメッセージは 500 Server Error: Internal Server Error for url: http://127.0.0.1:8765/broken でした。200 のときは何もせず None を返します。

import requests

for url in ["http://127.0.0.1:8765/broken",
            "http://127.0.0.1:8766/",
            "http://127.0.0.1:8765/slow"]:
    try:
        res = requests.get(url, timeout=3)
        res.raise_for_status()  # 4xx・5xx なら HTTPError を出す
        print(res.json())
    except requests.exceptions.HTTPError as e:
        print("HTTPError:", e.response.status_code, e.response.json())
    except requests.exceptions.ConnectionError:
        print("ConnectionError: 接続できませんでした")
    except requests.exceptions.Timeout:
        print("Timeout: 3 秒以内に応答がありませんでした")
HTTPError: 500 {'error': 'サーバー内部のエラー'}
ConnectionError: 接続できませんでした
Timeout: 3 秒以内に応答がありませんでした

requests が出す例外は、すべて requests.exceptions.RequestException を継承しています(公式ドキュメント)。分ける必要がなければ、これ 1 つでまとめて受け止められます。なお、接続の時間切れ ConnectTimeout は ConnectionError と Timeout の両方を継承している(2.34.2 で確認)ので、上の例では ConnectionError の側に入ります。try・except の基本は「Pythonの例外処理入門」で解説しています。

タイムアウトは必ず指定する

ここまでのコードには必ず timeout= を付けてきました。requests の公式ドキュメント(Quickstart)は、ほぼすべての本番のコードでこの引数を使うべきで、使わないとプログラムがいつまでも止まったままになる(hang indefinitely)おそれがあると書いています。明示しなければ、requests はタイムアウトしません。

urllib も同じです。urlopen で timeout を省くと socket の既定値が使われますが、Python の公式ドキュメントによると、その既定値は最初は None(タイムアウトなし)です。実際に、10 秒後に返す /slow に timeout なしで送ると、urllib も requests も 10.0 秒待ってから 200 を受け取りました。相手が返事をしなければ、10 秒どころか待ち続けることになります。

urlopen(".../slow", timeout=3) にすると、3.0 秒で TimeoutError: timed out が出ました。ただし urllib では時間切れになる段階で例外が変わります。接続そのものが時間切れのとき(応答しないアドレス 192.0.2.1 に送ったとき)は、URLError の reason に TimeoutError('timed out') が入っていました。両方を except で受け止めます。

requests では timeout=(3.05, 27) のように「接続を待つ秒数」と「返事を待つ秒数」を分けて指定できます。また timeout は全体の制限時間ではなく、データが届かない時間の上限です(公式ドキュメント)。少しずつ届き続ければ、合計はもっと長くなります。

文字コード:response.encoding と文字化け

requests の res.text は、受け取ったバイト列を res.encoding の文字コードで文字列にしたものです。公式ドキュメントによると、requests はまず HTTP ヘッダーの charset を見ます。そして、charset がなく Content-Type に text が含まれる場合は、ISO-8859-1 とみなします(古い HTTP の仕様 RFC 2616 の決まりに従っています)。そのため、charset を付けずに UTF-8 の日本語を返すサーバーでは文字化けします。

import requests

res = requests.get("http://127.0.0.1:8765/nocharset", timeout=5)
print(res.headers["content-type"], res.encoding)
print(res.text)
res.encoding = "utf-8"
print(res.text)
text/plain ISO-8859-1
ããã«ã¡ã¯
こんにちは

2 行目が文字化けした「こんにちは」です。res.encoding = "utf-8" と設定し直すと、3 行目のように読めました(res.content.decode("utf-8") でも同じ)。中身から推測した res.apparent_encoding はこの例では utf-8 でしたが、推測なので外れることもあります。

urllib は自動では文字列にしないので、res.headers.get_content_charset() でヘッダーの charset を取り出し、自分で decode します。文字化けの仕組みは「UTF-8とは?」も参考にしてください。

Cookie とセッション:ログイン状態を引き継ぐ

ログインするとサーバーが Set-Cookie ヘッダーでセッション ID を渡し、次のリクエストからはその Cookie を送ることで「ログイン中」と分かる、というのが Web の基本の仕組みです(「Cookieとセッションの仕組みとは?」で解説しています)。requests では、requests.Session() を使うと Cookie が自動で引き継がれます。

import requests

BASE = "http://127.0.0.1:8765"

with requests.Session() as s:
    print(s.get(BASE + "/me", timeout=5).status_code)
    s.post(BASE + "/login", data={"name": "hr"}, timeout=5)
    print(s.cookies.keys())
    print(s.get(BASE + "/me", timeout=5).json())

print(requests.get(BASE + "/me", timeout=5).json())  # セッションを使わないと Cookie は送られない
401
['sid']
{'user': 'hr'}
{'error': 'ログインしていません'}

ログイン前は 401、ログイン後は同じ Session からの /me が成功し、Session を使わない最後の requests.get は Cookie を送らないので 401 でした。

urllib では、http.cookiejar.CookieJar() を urllib.request.HTTPCookieProcessor に渡して build_opener で opener を作り、opener.open(...) で送ると Cookie が引き継がれます(同じ手順で {'user': 'hr'} が返ることを確認しました)。

実際のサイトに GET してみる(example.com)

説明用のドメイン example.com に 1 回だけ GET してみます。HTTPS でも書き方は同じで、証明書の検証も自動で行われます。

import requests

res = requests.get("https://example.com/", timeout=10)
print(res.status_code, res.headers["Content-Type"], res.encoding)
print(res.text[:60])
200 text/html; charset=utf-8 utf-8
<!doctype html><html lang=en><head><meta charset=utf-8><link

ヘッダーに charset=utf-8 があるので、encoding も utf-8 です(HTML の中身はサイト側の変更で変わることがあります)。

よくある間違い・トラブル

やったこと実際に出たエラー・結果直し方
urllib で URL に日本語をそのまま入れた(?q=入門)UnicodeEncodeError: 'ascii' codec can't encode charactersurllib.parse.urlencode で変換する
urllib の data= に文字列を渡したTypeError: POST data should be bytes, an iterable of bytes, or a file object. It cannot be of type str..encode("utf-8") で bytes にする
requests で data=json.dumps(...) と書いたサーバーに届いた Content-Type が空json=辞書 を使う
requests で res.json() だけ見て成功と判断した500 でもエラーの JSON が読めてしまうraise_for_status() か status_code を確認する

よくある質問

verify=False で証明書のエラーを消してもいいですか?

requests の公式ドキュメントは、verify=False にするとどんな証明書でも受け入れ、中間者攻撃(通信の途中で盗み見・書き換えをされる攻撃)に弱くなると警告しています。エラーを消す目的で使うのはやめ、原因(社内のプロキシ、期限切れの証明書など)を調べましょう。HTTPS の仕組みは「HTTPとHTTPSの違いとは?」で解説しています。

まとめ

urllib は標準だけで使える代わりに URL や本文の変換を自分で行い、requests は params=・json=・Session で短く書けます。どちらを使う場合も、timeout を必ず指定し、ステータスコードを確認し、トークンは環境変数から読むの 3 つを守りましょう。

関連する記事・ツール

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