Python Requestsライブラリ徹底解説：HTTP通信をもっと手軽に！🚀

Requestsの概要と特徴

requestsは、PythonでHTTPリクエストを送信するためのライブラリです。Kenneth Reitz氏によって開発され、Apache2ライセンスのもとで公開されています。標準のurllibと比較して、以下のような特徴があります。

• シンプルなAPI: 直感的で分かりやすいメソッド名や引数設計により、少ないコードでHTTPリクエストを記述できます。
• 豊富な機能: GET, POST, PUT, DELETEなどの主要なHTTPメソッドはもちろん、ヘッダーのカスタマイズ、クエリパラメータ、JSON/フォームデータの送信、ファイルアップロード、Cookieの管理、セッション維持、認証、タイムアウト設定、リダイレクトの自動処理、SSL証明書の検証など、HTTP通信に必要な機能が一通り揃っています。
• レスポンス処理の容易さ: レスポンスオブジェクトからステータスコード、ヘッダー、コンテンツ（テキスト、JSON、バイナリ）などを簡単に取得・処理できます。特にJSONレスポンスは.json()メソッドでPythonの辞書やリストに直接変換できます。
• エンコーディングの自動判別: レスポンスヘッダーなどから適切なエンコーディングを推測し、テキストデータをデコードしてくれます。
• 活発な開発とコミュニティ: 多くの開発者に利用されており、ドキュメントも充実しています。GitHubでのスター数も非常に多く、信頼性の高いライブラリです。

これらの特徴により、Webスクレイピング、APIクライアントの実装、Webサービスのテストなど、様々な場面でrequestsは活躍します。

インストール方法

requestsはサードパーティライブラリなので、使用する前にインストールが必要です。pipコマンドを使って簡単にインストールできます。

pip install requests

conda環境を使用している場合は、以下のコマンドでインストールできます。

conda install requests

インストールが完了したら、Pythonスクリプトやインタラクティブシェルでimport requestsと記述することで利用を開始できます。

import requests

# バージョン確認 (オプション)
print(requests.__version__)

requestsの基本的な使い方を見ていきましょう。ここでは、最もよく使われるGETリクエストとPOSTリクエストを中心に解説します。

GETリクエスト：データの取得

Webページの内容やAPIから情報を取得する際に使うのがGETリクエストです。requests.get()メソッドを使用します。

import requests

# 指定したURLにGETリクエストを送信
url = 'https://httpbin.org/get' # テスト用のURL
try:
    response = requests.get(url)

    # レスポンスの状態を確認
    response.raise_for_status() # ステータスコードが 200 OK でない場合に例外を発生させる

    # レスポンス内容の取得
    print(f"ステータスコード: {response.status_code}") # HTTPステータスコード (例: 200)
    print(f"レスポンスヘッダー: {response.headers}") # レスポンスヘッダー (辞書形式)
    print(f"エンコーディング: {response.encoding}") # 推測されたエンコーディング
    print(f"テキスト内容 (一部): \n{response.text[:200]}...") # テキスト形式のコンテンツ

except requests.exceptions.RequestException as e:
    print(f"リクエスト中にエラーが発生しました: {e}")

requests.get()はResponseオブジェクトを返します。このオブジェクトには、サーバーからの応答に関する様々な情報が含まれています。

• status_code: HTTPステータスコード（整数）。200番台なら成功、400番台ならクライアントエラー、500番台ならサーバーエラーを示します。
• headers: レスポンスヘッダー（辞書）。Content-Typeなどが含まれます。
• encoding: レスポンスボディのデコードに使われるエンコーディング。requestsが自動判別しますが、必要に応じてresponse.encoding = 'utf-8'のように手動で設定も可能です。
• text: デコードされたレスポンスボディ（文字列）。HTMLやテキストデータなどに使います。
• content: バイト列形式のレスポンスボディ。画像やファイルなどのバイナリデータに使います。
• json(): レスポンスボディをJSONとしてパースし、Pythonの辞書またはリストに変換します。Content-Typeがapplication/jsonでない場合や、JSONとして不正な形式の場合はエラーになります。

クエリパラメータ付きGETリクエスト

URLの末尾に?key1=value1&key2=value2のような形式でパラメータを追加したい場合があります。これをクエリパラメータ（またはクエリストリング）と呼びます。requestsでは、params引数に辞書を渡すことで簡単に実現できます。

import requests

url = 'https://httpbin.org/get'
# パラメータを辞書で定義
params = {'query': 'python requests', 'lang': 'ja'}

try:
    response = requests.get(url, params=params)
    response.raise_for_status()

    # requestsが自動でエンコードしてURLに追加してくれる
    print(f"リクエストしたURL: {response.url}")
    # レスポンス内容 (JSON) を表示
    print(response.json())

except requests.exceptions.RequestException as e:
    print(f"リクエスト中にエラーが発生しました: {e}")

params引数を使うと、URLエンコーディングなどを気にせずにパラメータを安全に追加できます。

POSTリクエスト：データの送信

サーバーにデータを送信する場合（例：フォームの送信、APIへのデータ登録）にはPOSTリクエストを使用します。requests.post()メソッドを使います。送信するデータの形式に応じて、data引数またはjson引数を使います。

フォームデータの送信 (data引数)

HTMLフォームのようなkey=value形式のデータを送信する場合は、data引数に辞書を渡します。requestsは自動的にapplication/x-www-form-urlencoded形式にエンコードしてくれます。

import requests

url = 'https://httpbin.org/post'
# 送信するフォームデータを辞書で定義
payload = {'username': 'taro', 'email': 'taro@example.com'}

try:
    response = requests.post(url, data=payload)
    response.raise_for_status()

    print(f"ステータスコード: {response.status_code}")
    # 送信したデータが 'form' キーに含まれていることを確認
    print(response.json())

except requests.exceptions.RequestException as e:
    print(f"リクエスト中にエラーが発生しました: {e}")

JSONデータの送信 (json引数)

APIなどでよく使われるJSON形式でデータを送信する場合は、json引数にPythonの辞書やリストを渡します。requestsは自動的にデータをJSON文字列にシリアライズし、リクエストヘッダーのContent-Typeをapplication/jsonに設定してくれます。👍

import requests
import json # jsonモジュールは requests が内部で使用するが、明示的にインポートしても良い

url = 'https://httpbin.org/post'
# 送信するJSONデータを辞書で定義
payload = {'item_id': 123, 'quantity': 5, 'options': {'color': 'red', 'size': 'M'}}

try:
    response = requests.post(url, json=payload) # json引数を使用
    response.raise_for_status()

    print(f"ステータスコード: {response.status_code}")
    # 送信したデータが 'json' キーに含まれていることを確認
    print(response.json())
    # Content-Typeヘッダーが application/json になっていることを確認
    print(f"リクエストヘッダーのContent-Type: {response.request.headers['Content-Type']}")

except requests.exceptions.RequestException as e:
    print(f"リクエスト中にエラーが発生しました: {e}")

以前はdata=json.dumps(payload)のように手動でJSON文字列に変換し、ヘッダーもheaders={'Content-Type': 'application/json'}と指定する必要がありましたが、json引数を使えばこれらの手間が省けます。非常に便利ですね！

その他のHTTPメソッド

requestsはGET, POST以外にも主要なHTTPメソッドに対応しています。

• requests.put(url, data=...): リソースの更新（全体を置き換え）
• requests.delete(url): リソースの削除
• requests.head(url): ヘッダーのみを取得（ボディは取得しない）
• requests.patch(url, data=...): リソースの部分的な更新
• requests.options(url): 利用可能なメソッドなどを問い合わせる

基本的な使い方はgetやpostと同様です。

import requests

url = 'https://httpbin.org/put'
payload = {'name': 'jiro', 'status': 'active'}
response = requests.put(url, json=payload)
print(f"PUT response: {response.status_code}")

url_delete = 'https://httpbin.org/delete'
response = requests.delete(url_delete)
print(f"DELETE response: {response.status_code}")

カスタムヘッダーの追加

APIキーの指定やUser-Agentの変更など、リクエストヘッダーをカスタマイズしたい場合は、headers引数に辞書を渡します。

import requests

url = 'https://httpbin.org/headers'
# カスタムヘッダーを辞書で定義
custom_headers = {
    'User-Agent': 'MyAwesomePythonClient/1.0',
    'X-API-Key': 'your_secret_api_key_here',
    'Accept-Language': 'ja-JP,ja;q=0.9'
}

try:
    response = requests.get(url, headers=custom_headers)
    response.raise_for_status()

    # レスポンスには送信したヘッダーが含まれている
    print(response.json())

except requests.exceptions.RequestException as e:
    print(f"リクエスト中にエラーが発生しました: {e}")

基本的なリクエストの送受信ができるようになったら、さらに便利な応用機能を見ていきましょう。

セッション (Session) オブジェクト：接続の維持と効率化

複数のリクエストを同じサーバーに対して行う場合（例：ログイン後に複数のページを操作する）、毎回接続を確立するのは非効率です。また、ログイン状態を維持するためにCookieをリクエスト間で保持する必要があります。

このような場合に役立つのがrequests.Sessionオブジェクトです。セッションオブジェクトを使うと、以下のメリットがあります。

• Cookieの永続化: セッション内で送受信されたCookieは自動的に保持され、後続のリクエストで送信されます。
• 接続の再利用: TCP接続を可能な限り再利用するため、パフォーマンスが向上します（Keep-Alive）。
• デフォルト設定の共有: ヘッダーや認証情報などをセッションオブジェクトに設定しておけば、そのセッションから送信されるすべてのリクエストに適用されます。

使い方は簡単で、まずrequests.Session()でインスタンスを作成し、そのインスタンスのメソッド（get(), post()など）を使ってリクエストを送信します。

import requests

# セッションオブジェクトを作成
session = requests.Session()

# セッションにデフォルトヘッダーを設定 (オプション)
session.headers.update({'User-Agent': 'MySessionClient/1.0'})

# ログイン処理 (例: Cookieが設定される)
login_url = 'https://httpbin.org/cookies/set/sessioncookie/123456789'
session.get(login_url) # このリクエストでCookieが設定される

# ログインが必要なページにアクセス (Cookieが自動で送信される)
protected_url = 'https://httpbin.org/cookies'
try:
    response = session.get(protected_url)
    response.raise_for_status()

    # レスポンスに先ほど設定されたCookieが含まれていることを確認
    print(response.json())

    # 別のページにもアクセス (同じセッションとCookieを使用)
    another_url = 'https://httpbin.org/get'
    response2 = session.get(another_url)
    response2.raise_for_status()
    print("別ページへのアクセスも成功")

except requests.exceptions.RequestException as e:
    print(f"セッション中のリクエストでエラーが発生しました: {e}")

# セッションを閉じる (リソース解放のため推奨、特に長時間実行するスクリプトの場合)
# with文を使うと自動的に閉じられる
with requests.Session() as s:
    s.get('https://httpbin.org/get')
    # withブロックを抜けると自動的に s.close() が呼ばれる
print("withブロックを使ったセッションは自動的に閉じられました。")

特にログインが必要なサイトのスクレイピングや、APIとの連続したやり取りでは、セッションオブジェクトの使用が推奨されます。

認証 (Authentication)

多くのWebサービスやAPIでは、リソースにアクセスするために認証が必要です。requestsはいくつかの一般的な認証方式を簡単に扱えるようにしています。

Basic認証 / Digest認証

最も基本的なHTTP認証方式です。auth引数にユーザー名とパスワードのタプルを渡すだけで利用できます。

import requests
from requests.auth import HTTPBasicAuth, HTTPDigestAuth

# Basic認証
basic_auth_url = 'https://httpbin.org/basic-auth/user/password'
try:
    # 方法1: auth引数にタプルを渡す
    response_basic = requests.get(basic_auth_url, auth=('user', 'password'))
    response_basic.raise_for_status()
    print(f"Basic認証成功: {response_basic.status_code}")
    print(response_basic.json())

    # 方法2: HTTPBasicAuthオブジェクトを使用
    # response_basic = requests.get(basic_auth_url, auth=HTTPBasicAuth('user', 'password'))

except requests.exceptions.RequestException as e:
    print(f"Basic認証中にエラーが発生しました: {e}")

# Digest認証 (httpbinはDigest認証のエンドポイントを提供していないため、概念的なコード)
# digest_auth_url = 'https://example.com/digest-auth'
# try:
#     response_digest = requests.get(digest_auth_url, auth=HTTPDigestAuth('user', 'password'))
#     response_digest.raise_for_status()
#     print(f"Digest認証成功: {response_digest.status_code}")
# except requests.exceptions.RequestException as e:
#     print(f"Digest認証中にエラーが発生しました: {e}")

OAuth認証など

OAuthのようなより複雑な認証フローについては、requests-oauthlibなどの拡張ライブラリを利用するのが一般的です。これらのライブラリはrequestsと連携して、認証トークンの取得やリクエストへの付与を自動化してくれます。

# requests-oauthlib のインストール
pip install requests-oauthlib

具体的な実装方法は利用するサービス（Twitter API, Google APIなど）のドキュメントを参照してください。

タイムアウト (Timeout)

ネットワークの問題やサーバーの応答遅延により、リクエストが完了せずにプログラムが停止してしまうことがあります。これを防ぐために、タイムアウト値を設定することが重要です。timeout引数に秒数を指定します。

import requests

url = 'https://httpbin.org/delay/5' # 5秒遅延して応答するURL

try:
    # タイムアウトを3秒に設定
    response = requests.get(url, timeout=3)
    response.raise_for_status()
    print("リクエスト成功（タイムアウト前）")

except requests.exceptions.Timeout:
    print("リクエストがタイムアウトしました。⏰")
except requests.exceptions.RequestException as e:
    print(f"タイムアウト以外のリクエストエラーが発生しました: {e}")

# 接続タイムアウトと読み取りタイムアウトを個別に設定することも可能
try:
    # 接続に1秒、読み取りに5秒まで待つ
    response = requests.get(url, timeout=(1, 5))
    response.raise_for_status()
    print("個別タイムアウト設定でリクエスト成功")
except requests.exceptions.ConnectTimeout:
     print("接続タイムアウトが発生しました。")
except requests.exceptions.ReadTimeout:
     print("読み取りタイムアウトが発生しました。")
except requests.exceptions.RequestException as e:
    print(f"個別タイムアウト設定中にエラーが発生しました: {e}")

timeout引数には、接続確立までのタイムアウトと、サーバーからの応答データ受信開始までのタイムアウトをタプル(connect_timeout, read_timeout)で指定することもできます。適切なタイムアウト値を設定することで、プログラムの応答性を保つことができます。

プロキシ (Proxy) の利用

特定のネットワーク環境下や、IPアドレスを隠したい場合などにプロキシサーバー経由でリクエストを送信する必要があります。proxies引数にプロトコル名をキー、プロキシアドレスを値とする辞書を渡します。

import requests

# プロキシサーバーのアドレスを設定
proxies = {
  'http': 'http://10.10.1.10:3128',
  'https': 'http://10.10.1.10:1080',
  # 必要に応じて認証情報を追加
  # 'http': 'http://user:password@10.10.1.10:3128/',
}

url = 'https://httpbin.org/ip' # アクセス元のIPアドレスを返すURL

try:
    # プロキシ経由でリクエストを送信
    response = requests.get(url, proxies=proxies, timeout=10)
    response.raise_for_status()
    # レスポンスにはプロキシサーバーのIPアドレスが表示されるはず
    print(response.json())

except requests.exceptions.ProxyError as e:
    print(f"プロキシエラーが発生しました: {e}")
except requests.exceptions.RequestException as e:
    print(f"プロキシ経由のリクエスト中にエラーが発生しました: {e}")

SSL証明書の検証

requestsはデフォルトでHTTPS接続時のSSL証明書を検証します。これにより、中間者攻撃などを防ぎ、安全な通信を確保します。しかし、自己署名証明書を使用している内部サーバーなど、検証を無効にしたい場合もあります（セキュリティリスクを理解した上で行ってください）。その場合はverify=Falseを指定します。

import requests
# requests は verify=False を使うと警告を出すので、それを抑制する (非推奨)
# from requests.packages.urllib3.exceptions import InsecureRequestWarning
# requests.packages.urllib3.disable_warnings(InsecureRequestWarning)

url = 'https://self-signed.badssl.com/' # 自己署名証明書のテストサイト

# デフォルト (verify=True) では SSL エラーになるはず
try:
    response = requests.get(url, timeout=5)
    print("証明書検証成功？ (通常はエラーになるはず)")
except requests.exceptions.SSLError as e:
    print(f"SSL証明書の検証に失敗しました (想定通り): {e}")

# 検証を無効にする (非推奨)
try:
    response_noverify = requests.get(url, verify=False, timeout=5)
    response_noverify.raise_for_status()
    print(f"証明書検証を無効にしてアクセス成功: {response_noverify.status_code}")
    # print(response_noverify.text) # 内容の表示は省略
except requests.exceptions.RequestException as e:
    print(f"証明書検証無効でもエラーが発生しました: {e}")

# 特定のCAバンドルファイルを指定することも可能
# response_custom_ca = requests.get(url, verify='/path/to/custom/ca.pem')

⚠️ 注意: 公開サーバーに対してverify=Falseを使用することは、セキュリティ上の大きなリスクを伴います。中間者攻撃に対して脆弱になるため、特別な理由がない限り避けるべきです。

外部のサービスと通信する際には、予期せぬエラーが発生する可能性があります。堅牢なアプリケーションを構築するためには、適切なエラーハンドリングが不可欠です。また、requestsをより効果的に使うためのベストプラクティスもいくつかあります。

エラーハンドリング：例外処理

requestsは、さまざまなエラー状況に対応する例外クラスを提供しています。主なものを以下に示します。これらはすべてrequests.exceptions.RequestExceptionを継承しています。

これらの例外をtry...exceptブロックで捕捉することで、エラー発生時にもプログラムがクラッシュするのを防ぎ、適切な処理（ログ記録、リトライ、デフォルト値の使用など）を行うことができます。

import requests
import time

url = 'http://example.invalid' # 存在しないURL (ConnectionErrorを発生させる)
# url = 'https://httpbin.org/status/500' # サーバーエラー (HTTPErrorを発生させる)
# url = 'https://httpbin.org/delay/10' # 遅延 (Timeoutを発生させる)

retries = 3
delay = 2 # リトライ間の待機時間 (秒)

for i in range(retries):
    try:
        print(f"リクエスト試行 {i+1}/{retries}...")
        response = requests.get(url, timeout=5)
        # ステータスコードチェック
        response.raise_for_status()
        # 成功した場合の処理
        print("リクエスト成功！")
        print(f"コンテンツの一部: {response.text[:100]}...")
        break # 成功したらループを抜ける

    except requests.exceptions.ConnectTimeout as e:
        print(f"接続タイムアウト: {e}")
    except requests.exceptions.ReadTimeout as e:
        print(f"読み取りタイムアウト: {e}")
    except requests.exceptions.ConnectionError as e:
        print(f"接続エラー: {e}")
    except requests.exceptions.HTTPError as e:
        print(f"HTTPエラー: {e.response.status_code} - {e}")
        # サーバーエラー(5xx)の場合はリトライするかもしれない
        if 500 <= e.response.status_code < 600:
            print("サーバーエラーのためリトライします...")
        else:
            # クライアントエラー(4xx)はリトライしても無駄なことが多い
            print("クライアントエラーのためリトライしません。")
            break
    except requests.exceptions.RequestException as e:
        # その他の requests 由来のエラー
        print(f"予期せぬリクエストエラー: {e}")
        break # 不明なエラーはリトライしない

    # リトライ前に待機
    if i < retries - 1:
        print(f"{delay}秒待機してリトライします...")
        time.sleep(delay)
    else:
        print("最大リトライ回数に達しました。")

print("処理終了。")

上記のように、具体的な例外から捕捉し、最後に汎用的なRequestExceptionで捕捉するのが一般的なパターンです。エラーの種類に応じてリトライするかどうかを判断することも重要です。

ベストプラクティス

requestsをより効果的かつ安全に使うための推奨事項です。

• 常にタイムアウトを設定する: 外部サービスへのリクエストには、予期せぬ遅延がつきものです。timeout引数を設定し、プログラムが無限に待機状態になるのを防ぎましょう。
• セッションオブジェクトを活用する: 同じホストに複数のリクエストを送る場合は、requests.Session()を使いましょう。パフォーマンスが向上し、Cookie管理も容易になります。with文を使うと後片付けも自動で行われます。
• 適切な例外処理を行う: try...exceptブロックでrequestsの例外を捕捉し、ネットワークエラーやHTTPエラーに備えましょう。response.raise_for_status()を使ってHTTPエラーを簡単にチェックできます。
• エラー時のリトライ戦略を検討する: 一時的なネットワークの問題やサーバーの過負荷でリクエストが失敗することがあります。指数バックオフ（Exponential Backoff）などのリトライ戦略を実装することで、システムの回復力を高めることができます。（requests自体には組み込みのリトライ機能はありませんが、urllib3のRetryクラスやtenacityライブラリなどと組み合わせることで実現可能です。）
• ステータスコードを確認する: response.status_codeをチェックし、リクエストが期待通りに成功したか（通常は2xx系）を確認しましょう。
• User-Agentを設定する: 特にWebスクレイピングを行う場合、デフォルトのUser-Agent（例: python-requests/2.31.0）だとアクセスを拒否されることがあります。実際のブラウザに近いUser-Agent文字列を設定することを検討しましょう。ただし、サイトの利用規約（robots.txtなど）は遵守してください。
• 大量のリクエストは段階的に: 大量のデータを取得する場合、APIのページネーション機能を利用したり、一度にすべてのデータをメモリにロードせずストリーミング（response.iter_content()など）で処理したりすることを検討しましょう。サーバーへの負荷軽減にもつながります。
• SSL証明書の検証を無効にしない: セキュリティ上の理由から、verify=Falseの使用は極力避けましょう。必要な場合は、信頼するCA証明書を指定（verify='/path/to/ca.pem'）する方が安全です。
• ライブラリを最新に保つ: requestsは活発に開発されています。セキュリティ修正や新機能の恩恵を受けるために、定期的にライブラリをアップデートしましょう (pip install --upgrade requests)。

Pythonのrequestsライブラリは、そのシンプルさと強力な機能により、HTTP通信を扱う際のデファクトスタンダードとなっています。基本的なGET/POSTリクエストから、セッション管理、認証、エラーハンドリングまで、幅広いニーズに対応できます。

この記事で解説した内容を参考に、ぜひrequestsを使いこなして、WebスクレイピングやAPI連携、その他HTTP通信が必要なタスクを効率的に進めてください。使いやすく、強力なrequestsライブラリが、あなたのPythonプログラミングをさらに快適なものにしてくれるでしょう！🎉

非同期処理が必要な場合は、requestsとAPI互換性があり非同期に対応した HTTPX や、より高パフォーマンスな AIOHTTP といったライブラリも検討してみると良いでしょう。