はい、承知いたしました。PythonでHTTPリクエストを行う際の基本と、requestsライブラリの詳細な使い方について、約5000語を目標とした解説記事を記述します。

Pythonで学ぶHTTPリクエストの基本と`requests`ライブラリの詳細

はじめに

インターネットは、Webサイトの閲覧、オンラインサービスの利用、スマートフォンアプリのデータ通信など、私たちの日常生活に不可欠なインフラとなっています。これらの多くは、HTTP (Hypertext Transfer Protocol) という通信プロトコルに基づいています。WebブラウザがサーバーからWebページを取得するのも、スマートフォンアプリがAPIを通じてデータをやり取りするのも、このHTTPリクエストとレスポンスによって成り立っています。

プログラミングにおいて、HTTPリクエストを扱う能力は非常に重要です。
* データの取得: Web上の公開情報（ニュース、天気予報など）や、APIで提供されるデータ（株価、為替レートなど）を取得したい場合。
* サービスの連携: 外部サービス（SNS、ストレージサービスなど）のAPIを利用して、データの投稿、更新、削除などの操作を行いたい場合。
* Webスクレイピング: プログラムを使ってWebサイトの情報を収集したい場合（ただし、サイトの利用規約を確認し、適切な方法で行う必要があります）。
* 自動化: 定期的に特定のURLにアクセスして情報をチェックしたり、操作を実行したりしたい場合。

Pythonは、その豊富なライブラリとシンプルな構文により、HTTPリクエストを扱うのに非常に適した言語です。Pythonの標準ライブラリにもurllibやhttp.clientといったHTTPクライアント機能を提供するモジュールがありますが、より直感的で使いやすく、高機能な外部ライブラリとして広く使われているのがrequestsです。

この記事では、まずHTTPプロトコルの基本的な概念を解説し、その後、Pythonのrequestsライブラリを使ってどのようにHTTPリクエストを実行し、レスポンスを処理するのかを詳細に説明します。GET、POSTといった基本的なメソッドから、ヘッダーやパラメータの指定、タイムアウト、認証、セッション管理、エラーハンドリングといった高度な機能まで、具体的なコード例を交えながら網羅的に解説していきます。この記事を読めば、PythonでHTTPリクエストを自在に操るための基礎から応用までを習得できるでしょう。

HTTPプロトコルの基礎

requestsライブラリの使い方を学ぶ前に、まずHTTPプロトコルがどのように機能するのか、その基本を理解しておくことが重要です。

クライアントとサーバー

HTTPは、クライアントとサーバーの間で行われる通信プロトコルです。
* クライアント: Webブラウザや、Pythonスクリプトなど、リクエストを送信する側です。
* サーバー: WebサーバーやAPIサーバーなど、リクエストを受け取り、処理してレスポンスを返す側です。

通信は常にクライアントからのリクエストで始まり、サーバーからのレスポンスで終わります。これは「リクエスト-レスポンスモデル」と呼ばれます。

HTTPメソッド詳解

HTTPリクエストの最も重要な要素の一つが「HTTPメソッド」です。これは、クライアントがサーバー上のリソースに対してどのような操作を行いたいかを示します。代表的なメソッドには以下のものがあります。

GET: 指定したURI（Uniform Resource Identifier）にあるリソースのデータを取得するために使用されます。データを取得するだけで、サーバー側の状態を変更しないべき等（Idempotent）かつ安全（Safe）なメソッドとされています。クエリパラメータを使って追加情報を渡すことができますが、リクエストボディは通常持ちません。
POST: サーバーにデータを送信し、新しいリソースを作成したり、既存のリソースを更新したりするために使用されます。Webフォームの送信や、RESTful APIで新しいデータを登録する際によく使われます。リクエストボディに送信するデータを含めます。べき等でも安全でもありません。
PUT: 指定したURIにリクエストボディのデータを格納します。もしURIにリソースが存在しなければ新規作成し、存在すれば更新します。べき等ですが、安全ではありません。
DELETE: 指定したURIにあるリソースを削除するために使用されます。べき等ですが、安全ではありません。
HEAD: GETメソッドと同様にリソースのヘッダー情報のみを取得します。レスポンスボディは含まれません。リソースが存在するか、ヘッダー情報を確認したい場合に便利です。安全かつべき等です。
OPTIONS: 指定したURIのリソースがサポートしているHTTPメソッドを問い合わせるために使用されます。クロスオリジンリソース共有 (CORS) におけるプリフライトリクエストなどで使われます。安全かつべき等です。

通常、Web APIでは、GETはデータの参照、POSTはデータの作成、PUTはデータの更新、DELETEはデータの削除に割り当てられることが多く、これはRESTful APIの設計原則に基づいています。

URLの構造

HTTPリクエストの対象となるリソースは、URIによって一意に識別されます。一般的なURIであるURL (Uniform Resource Locator) は、以下の要素で構成されます。

scheme://host:port/path?query#fragment

scheme (スキーム): 使用するプロトコルを示します（例: http, https）。httpsはHTTPにSSL/TLSによる暗号化を追加したより安全なプロトコルです。
host (ホスト): リソースが存在するサーバーのホスト名またはIPアドレスです（例: www.example.com, 192.168.1.1）。
port (ポート): サーバーがHTTPリクエストを待ち受けているポート番号です。HTTPのデフォルトは80、HTTPSのデフォルトは443なので、これらのポート番号の場合は省略されることが多いです（例: :8080）。
path (パス): サーバー上のリソースの場所を示します（例: /users/profile, /api/v1/items/123）。
query (クエリ): リソースに対して渡す追加のパラメータです。キーと値のペアのリストとして、?key1=value1&key2=value2 の形式で表現されます。主にGETリクエストで使われます。
fragment (フラグメント): URIの一部ですが、これはクライアント側（通常はブラウザ）がリソース内の特定の場所（HTMLドキュメント内のアンカーなど）を指定するために使用するもので、サーバーには送信されません。

主要なHTTPヘッダーとその役割

HTTPリクエストおよびレスポンスには、本体（ボディ）とは別に「ヘッダー」が含まれます。ヘッダーは、通信に関する付加情報を提供します。例えば、リクエストヘッダーはクライアントに関する情報や、クライアントが求めるレスポンスの形式などをサーバーに伝え、レスポンスヘッダーはサーバーに関する情報や、レスポンスボディの内容などを示します。

一般的なリクエストヘッダーの例:
* User-Agent: クライアント（リクエストを送信しているアプリケーション、例: Webブラウザの種類やバージョン、スクリプト名など）の情報。
* Accept: クライアントが受け入れ可能なメディアタイプ（MIMEタイプ）。例: application/json, text/html。
* Accept-Language: クライアントが受け入れ可能な言語。
* Content-Type: リクエストボディに含まれるデータのメディアタイプ。POSTリクエストでJSONデータを送信する場合などにapplication/jsonを指定します。
* Content-Length: リクエストボディのサイズ（オクテット単位）。
* Authorization: 認証情報（ベーシック認証やトークンなど）。
* Cookie: サーバーから以前受け取ったクッキー。
* Referer: このリクエストがどこからリンクされたかを示すURL。

一般的なレスポンスヘッダーの例:
* Content-Type: レスポンスボディに含まれるデータのメディアタイプ。
* Content-Length: レスポンスボディのサイズ。
* Set-Cookie: クライアントに保存させるクッキー。
* Location: リダイレクト先のURL (3xx ステータスコードの場合)。
* Server: サーバーソフトウェアの情報。

HTTPステータスコード一覧と意味

サーバーはリクエストを処理した後、その結果を「ステータスコード」という3桁の数値でクライアントに伝えます。このコードを見れば、リクエストが成功したのか、失敗したのか、あるいは他の処理が必要なのかがわかります。

主要なステータスコードのカテゴリ:
* 1xx (Informational): リクエストは受信され、処理は続行中です。
* 例: 100 Continue (リクエストの一部が受け付けられ、残りのリクエストボディを送信する必要があることを示す)
* 2xx (Success): リクエストは正常に処理されました。
* 例: 200 OK (リクエストは成功し、リソースはレスポンスボディに含まれています)
* 例: 201 Created (リクエストは成功し、新しいリソースが作成されました)
* 例: 204 No Content (リクエストは成功しましたが、レスポンスボディはありません)
* 3xx (Redirection): クライアントはリクエストを完了するために、別の場所にリダイレクトされる必要があります。
* 例: 301 Moved Permanently (リソースは恒久的に新しいURIへ移動しました)
* 例: 302 Found (リソースは一時的に別のURIにあります)
* 例: 303 See Other (他のURIをGETメソッドで取得する必要があります)
* 例: 304 Not Modified (リソースは変更されていません – クライアントはキャッシュされたレスポンスを使用できます)
* 4xx (Client Error): クライアントのリクエストにエラーがあります。
* 例: 400 Bad Request (リクエストの構文が無効です)
* 例: 401 Unauthorized (認証が必要です)
* 例: 403 Forbidden (リソースへのアクセスが拒否されました)
* 例: 404 Not Found (要求されたリソースが見つかりません)
* 例: 405 Method Not Allowed (このリソースでは指定されたメソッドは許可されていません)
* 例: 429 Too Many Requests (短時間のうちにあまりに多くのリクエストを送信しました – レート制限)
* 5xx (Server Error): サーバーがリクエストの処理に失敗しました。
* 例: 500 Internal Server Error (サーバーで予期しないエラーが発生しました)
* 例: 503 Service Unavailable (サーバーは一時的に過負荷またはメンテナンス中です)

これらのステータスコードを理解することで、リクエストが成功したかどうか、そして失敗した場合はその原因を判断するのに役立ちます。

リクエストとレスポンスの構造

HTTP通信は、リクエストメッセージとレスポンスメッセージの交換です。

リクエストメッセージの一般的な構造:
1. リクエスト行: [メソッド] [URI] [HTTPバージョン] (例: GET /index.html HTTP/1.1)
2. ヘッダー: [ヘッダー名]: [値] の形式で複数行続く。空行でヘッダーの終わりを示す。
3. ボディ: GETメソッドなどの一部のリクエストではボディは含まれない。POST, PUTなどのリクエストでは、送信するデータが含まれる。

レスポンスメッセージの一般的な構造:
1. ステータス行: [HTTPバージョン] [ステータスコード] [理由フレーズ] (例: HTTP/1.1 200 OK)
2. ヘッダー: [ヘッダー名]: [値] の形式で複数行続く。空行でヘッダーの終わりを示す。
3. ボディ: 取得したリソースのデータが含まれる（HTML、JSON、画像データなど）。

この基礎知識があれば、requestsライブラリを使った操作がより深く理解できるようになります。

`requests`ライブラリの導入と基本

PythonでHTTPリクエストを扱うための選択肢はいくつかありますが、現在最も一般的で推奨されているのがrequestsライブラリです。

なぜ`requests`か？ (`urllib`との比較)

Pythonの標準ライブラリにはurllibやurllib2（Python 2）、http.clientなどのモジュールがあり、これらを使ってもHTTPリクエストは可能です。しかし、これらの標準ライブラリは使い方がやや複雑で、特に以下のような点でrequestsに比べて劣ります。

使いやすさ: urllibで簡単なGETリクエストをするだけでも複数行のコードが必要になることがあります。requestsは非常に直感的で、ほとんどの操作を1行または数行で記述できます。
機能: requestsは、リダイレクトの自動処理、セッション管理（クッキーの自動保持、TCP接続の再利用）、SSL証明書の検証、プロキシ、認証、タイムアウトなどの高度な機能を簡単に扱えます。標準ライブラリでこれらを実現しようとすると、多くのコードを書く必要があります。
エラーハンドリング: requestsはHTTPステータスコードに基づいたエラー処理を容易に行える機能を持っています。
国際化対応: requestsはレスポンスのエンコーディングを自動的に判別し、適切に処理します。

以下に、簡単なGETリクエストを標準ライブラリのurllib.requestとrequestsで比較する例を示します。

urllib.requestを使った例:

“`python
import urllib.request
import urllib.error

url = ‘https://httpbin.org/get’

try:
# URLを開く（リクエストを送信）
with urllib.request.urlopen(url) as response:
# レスポンスボディを読み込む
body = response.read()
# レスポポンスボディをデコード（エンコーディングを指定する必要がある場合がある）
decoded_body = body.decode(‘utf-8’) # エンコーディングの自動判別は難しい
# ヘッダーを取得
headers = response.getheaders()
# ステータスコードを取得
status_code = response.getcode()

    print(f"Status Code: {status_code}")
    print("Headers:")
    for name, value in headers:
        print(f"  {name}: {value}")
    print("Body:")
    print(decoded_body)

except urllib.error.URLError as e:
print(f”URL Error: {e.reason}”)
except urllib.error.HTTPError as e:
print(f”HTTP Error: {e.code} – {e.reason}”)
except Exception as e:
print(f”An unexpected error occurred: {e}”)

出力例（httpbin.orgはリクエスト情報を返すサービス）

Status Code: 200

Headers:

Date: …

Content-Type: application/json

…

Body:

{

“args”: {},

“headers”: {

“Accept-Encoding”: “identity”,

“Host”: “httpbin.org”,

“User-Agent”: “Python-urllib/3.x”, # 環境による

“X-Amzn-Trace-Id”: “…”

},

“origin”: “…”,

“url”: “https://httpbin.org/get”

}

“`

requestsを使った例:

“`python
import requests

url = ‘https://httpbin.org/get’

try:
# URLにGETリクエストを送信
response = requests.get(url)

# ステータスコードを確認し、200番台以外の場合は例外を発生させる
response.raise_for_status()

# レスポンスボディ（テキスト形式、エンコーディング自動判別）
text_body = response.text
# レスポンスボディ（JSON形式、自動パース）
json_body = response.json()
# レスポンスボディ（バイナリ形式）
binary_body = response.content
# ヘッダーを取得 (辞書ライクなオブジェクト)
headers = response.headers
# ステータスコードを取得
status_code = response.status_code
# 経過時間を取得
elapsed_time = response.elapsed

print(f"Status Code: {status_code}")
print(f"Elapsed Time: {elapsed_time}")
print("Headers:")
for name, value in headers.items(): # 辞書のように扱える
    print(f"  {name}: {value}")
print("Body (JSON):")
print(json_body) # 辞書として扱える

except requests.exceptions.RequestException as e:
# requests関連のエラーをまとめて捕捉
print(f”Request Error: {e}”)
except Exception as e:
print(f”An unexpected error occurred: {e}”)

出力例（urllibと同じ内容だが、コードがより簡潔）

Status Code: 200

Elapsed Time: 0:00:…

Headers:

Date: …

Content-Type: application/json

…

Body (JSON):

{‘args’: {}, ‘headers’: {‘Accept’: ‘/‘, ‘Accept-Encoding’: ‘gzip, deflate’, ‘Host’: ‘httpbin.org’, ‘User-Agent’: ‘python-requests/2.x.x’, ‘X-Amzn-Trace-Id’: ‘…’}, ‘origin’: ‘…’, ‘url’: ‘https://httpbin.org/get’}

“`

ご覧のように、requestsを使うと、コードが格段に簡潔になり、直感的になります。ステータスコードの確認やJSONデータのパースなども容易に行えます。これが、PythonでHTTPリクエストを扱う際にrequestsが標準的に使用される理由です。

インストール方法

requestsは外部ライブラリなので、使用する前にインストールが必要です。Pythonのパッケージ管理システムであるpipを使って簡単にインストールできます。コマンドプロンプトまたはターミナルを開き、以下のコマンドを実行してください。

bash pip install requests

これにより、requestsライブラリとその依存関係がインストールされます。

最初のGETリクエスト

インストールが完了したら、早速最初のHTTPリクエストを実行してみましょう。最も基本的なGETリクエストを送信して、Webページのコンテンツを取得してみます。ここでは、先ほども例で使ったリクエスト情報確認サービス httpbin.org を利用します。

“`python
import requests

リクエストを送信したいURL

url = ‘https://httpbin.org/get’

GETリクエストを送信

response = requests.get(url)

レスポンスオブジェクトの中身を確認

print(f”Status Code: {response.status_code}”) # ステータスコード
print(f”Response Body (Text):\n{response.text}”) # レスポンスボディをテキストとして取得
print(f”Response Headers:\n{response.headers}”) # レスポンスヘッダー
print(f”Is Successful? (status_code < 400): {response.ok}”) # ステータスコードが400未満ならTrue
print(f”Elapsed Time: {response.elapsed}”) # リクエスト送信からレスポンス受信までの経過時間
print(f”Request URL: {response.url}”) # 最終的にアクセスしたURL (リダイレクト後など)

レスポンスがJSON形式であることを期待する場合

try:
print(f”Response Body (JSON):\n{response.json()}”)
except requests.exceptions.JSONDecodeError:
print(“Response body is not in JSON format.”)
“`

このコードを実行すると、httpbin.org/getにGETリクエストが送信され、そのリクエストに関する情報（IPアドレス、ヘッダーなど）をJSON形式で返すレスポンスを受け取ります。requests.get()関数は、リクエストの結果を表すResponseオブジェクトを返します。このオブジェクトを通じて、ステータスコード、ヘッダー、ボディなどのレスポンスの詳細にアクセスできます。

`requests`を使った基本的なHTTPメソッド

requestsライブラリは、HTTPの主要なメソッドに対応する簡単な関数を提供しています。

requests.get()
requests.post()
requests.put()
requests.delete()
requests.head()
requests.options()

これらの関数は、いずれも第一引数にターゲットとなるURLを受け取ります。

GETリクエストの詳細（クエリパラメータ）

GETリクエストはデータの取得に使われ、サーバーに渡す追加情報はクエリパラメータとしてURLに含めるのが一般的です。requestsでは、URLに直接クエリパラメータを含めることも可能ですが、params引数に辞書を渡すのが推奨されます。requestsが自動的にキーと値をURLエンコードし、URLに付加してくれます。

“`python
import requests

url = ‘https://httpbin.org/get’

クエリパラメータを辞書で定義

parameters = {
‘key1’: ‘value1’,
‘key2’: ‘日本語の値’ # 日本語も安全に扱える
}

params引数に辞書を渡してGETリクエストを送信

response = requests.get(url, params=parameters)

print(f”Status Code: {response.status_code}”)
print(f”Request URL: {response.url}”) # エンコードされたURLが表示されるはず
print(f”Response Body (JSON):\n{response.json()}”)

出力例

Status Code: 200

Request URL: https://httpbin.org/get?key1=value1&key2=%E6%97%A5%E6%9C%AC%E8%AA%9E%E3%81%AE%E5%80%A4 # %エンコードされている

Response Body (JSON):

{‘args’: {‘key1’: ‘value1’, ‘key2’: ‘日本語の値’}, …} # httpbinがパースして表示

“`

辞書の値がリストの場合、requestsは同じキーで複数のクエリパラメータを生成します。

“`python
parameters = {
‘ids’: [‘100’, ‘200’, ‘300’]
}

response = requests.get(url, params=parameters)

print(f”Request URL: {response.url}”)

出力例

Request URL: https://httpbin.org/get?ids=100&ids=200&ids=300

“`

POSTリクエストの詳細（`data` vs `json`）

POSTリクエストはデータを送信し、新しいリソースを作成したり、既存のリソースを更新したりするのに使われます。送信するデータはリクエストボディに含まれます。requestsでは、リクエストボディの指定方法として主にdata引数とjson引数があります。

data引数: フォーム形式（application/x-www-form-urlencoded）またはマルチパート形式（multipart/form-data）のデータを送信する場合に使用します。辞書、バイト列、またはファイルのようなオブジェクトを渡すことができます。辞書を渡すと、自動的にフォーム形式にエンコードされます。
json引数: JSON形式（application/json）のデータを送信する場合に使用します。辞書またはリストを渡すと、自動的にJSON文字列に変換され、Content-Type: application/jsonヘッダーが設定されます。RESTful APIとの連携で最もよく使われます。

フォーム形式のPOSTリクエスト:

“`python
import requests

url = ‘https://httpbin.org/post’

フォームデータを辞書で定義

form_data = {
‘name’: ‘Alice’,
‘age’: ’30’,
‘message’: ‘Hello, World!’
}

data引数に辞書を渡してPOSTリクエストを送信

response = requests.post(url, data=form_data)

print(f”Status Code: {response.status_code}”)
print(f”Response Body (JSON):\n{response.json()}”) # httpbin.orgはPOSTされたデータをJSONで返す

出力例

Status Code: 200

Response Body (JSON):

{‘args’: {}, ‘data’: ”, ‘files’: {}, ‘form’: {‘age’: ’30’, ‘message’: ‘Hello, World!’, ‘name’: ‘Alice’}, …}

formキーの下に送信したフォームデータが確認できる

“`

JSON形式のPOSTリクエスト:

“`python
import requests

url = ‘https://httpbin.org/post’

JSONデータを辞書で定義

json_payload = {
‘user_id’: 123,
‘username’: ‘bob_smith’,
‘email’: ‘[email protected]’,
‘is_active’: True
}

json引数に辞書を渡してPOSTリクエストを送信

response = requests.post(url, json=json_payload)

print(f”Status Code: {response.status_code}”)
print(f”Response Body (JSON):\n{response.json()}”) # httpbin.orgはPOSTされたデータをJSONで返す

出力例

Status Code: 200

Response Body (JSON):

{‘args’: {}, ‘data’: ‘{“user_id”: 123, “username”: “bob_smith”, “email”: “[email protected]”, “is_active”: true}’, ‘files’: {}, ‘form’: {}, ‘json’: {‘email’: ‘[email protected]’, ‘is_active’: True, ‘user_id’: 123, ‘username’: ‘bob_smith’}, …}

jsonキーの下に送信したJSONデータがパースされた状態で確認できる。

また、レスポンスヘッダーには Content-Type: application/json が自動で付与されているはず。

“`

dataとjsonは同時に指定できません。どちらか一方を使用します。APIのドキュメントを確認して、どちらの形式でデータを送信する必要があるか確認しましょう。

PUTリクエスト

PUTリクエストは、指定されたURIにリクエストボディの内容を格納するために使用されます。通常、既存のリソースを完全に新しいデータで置き換える際に使われます。

“`python
import requests

url = ‘https://httpbin.org/put’

更新データを辞書で定義

update_data = {
‘item_id’: 456,
‘status’: ‘completed’
}

put関数にURLとdataまたはjsonを渡してPUTリクエストを送信

response = requests.put(url, json=update_data)

print(f”Status Code: {response.status_code}”)
print(f”Response Body (JSON):\n{response.json()}”) # httpbin.orgはPUTされたデータをJSONで返す

出力例

Status Code: 200

Response Body (JSON):

{‘args’: {}, ‘data’: ‘{“item_id”: 456, “status”: “completed”}’, ‘files’: {}, ‘form’: {}, ‘json’: {‘item_id’: 456, ‘status’: ‘completed’}, …}

jsonキーの下に送信したJSONデータが確認できる。

“`

DELETEリクエスト

DELETEリクエストは、指定されたURIのリソースを削除するために使用されます。通常、リクエストボディは含まれません。

“`python
import requests

削除対象のURIを指定

url = ‘https://httpbin.org/delete’ # httpbin.orgでは実際に削除は行われませんが、DELETEリクエストを受け付けます

delete関数にURLを渡してDELETEリクエストを送信

response = requests.delete(url)

print(f”Status Code: {response.status_code}”)
print(f”Response Body (JSON):\n{response.json()}”) # httpbin.orgはDELETEリクエストに関する情報をJSONで返す

出力例

Status Code: 200

Response Body (JSON):

{‘args’: {}, ‘data’: ”, ‘files’: {}, ‘form’: {}, ‘headers’: {…}, ‘json’: None, ‘origin’: ‘…’, ‘url’: ‘https://httpbin.org/delete’}

“`

HEADとOPTIONSリクエスト

requests.head()はGETと同様のリクエストを送信しますが、レスポンスボディをダウンロードしません。ヘッダー情報やステータスコードのみを確認したい場合に効率的です。

requests.options()は、指定したURIのリソースがサポートしているメソッドなどを確認します。CORS関連で使われることが多いですが、一般的なアプリケーションコードで直接呼び出す機会は少ないかもしれません。

“`python
import requests

url = ‘https://www.google.com’

HEADリクエスト

head_response = requests.head(url)
print(f”HEAD Status Code: {head_response.status_code}”)
print(f”HEAD Headers:\n{head_response.headers}”)
print(f”HEAD Body (will be empty): {head_response.text}”) # レスポンスボディは空

OPTIONSリクエスト (多くのサイトで許可されていない場合があります)

try:

options_response = requests.options(url)

print(f”OPTIONS Status Code: {options_response.status_code}”)

print(f”OPTIONS Allow Header: {options_response.headers.get(‘Allow’)}”) # 許可されているメソッドなどが含まれる

except requests.exceptions.RequestException as e:

print(f”OPTIONS Request Failed: {e}”)

“`

リクエストのカスタマイズ

requestsライブラリの強力な点の一つは、リクエストを細かくカスタマイズできることです。ヘッダーの追加、タイムアウトの設定、プロキシの使用など、様々なオプションが用意されています。これらのオプションは、requests.get(), requests.post()などのメソッドにキーワード引数として渡します。

カスタムヘッダーの設定

リクエストヘッダーは、クライアントの情報やリクエストに関する追加情報をサーバーに伝えるために使用されます。特定のAPIでは、認証トークンをヘッダーで渡したり、応答形式を指定したりすることが必須です。カスタムヘッダーはheaders引数に辞書として渡します。

“`python
import requests

url = ‘https://httpbin.org/headers’ # 送信されたヘッダー情報を返すサービス

カスタムヘッダーを辞書で定義

custom_headers = {
‘User-Agent’: ‘MyPythonApp/1.0’, # デフォルトのUser-Agentを上書き
‘Accept’: ‘application/json’, # JSON形式のレスポンスを要求
‘X-My-Custom-Header’: ‘SomeValue’, # 独自のヘッダー
# ‘Authorization’: ‘Bearer your_access_token_here’ # 例: トークン認証の場合
}

headers引数にカスタムヘッダー辞書を渡してGETリクエストを送信

response = requests.get(url, headers=custom_headers)

print(f”Status Code: {response.status_code}”)
print(f”Response Body (JSON):\n{response.json()}”) # httpbin.orgは受け取ったヘッダーをJSONで返す

出力例

Status Code: 200

Response Body (JSON):

{‘headers’: {‘Accept’: ‘application/json’, ‘Accept-Encoding’: ‘gzip, deflate’, ‘Host’: ‘httpbin.org’, ‘User-Agent’: ‘MyPythonApp/1.0’, ‘X-My-Custom-Header’: ‘SomeValue’, ‘X-Amzn-Trace-Id’: ‘…’}}

定義したカスタムヘッダーがUser-Agent含めて含まれていることが確認できる。

“`

タイムアウトの設定（接続と読み込み）

ネットワークの遅延やサーバーの応答がない場合に、いつまでもリクエストがブロックされないように、タイムアウトを設定することは非常に重要です。timeout引数に秒数を指定します。

timeoutは、以下の2つの段階のタイムアウトを指定できます。
1. 接続タイムアウト: クライアントがサーバーへの接続を確立するまでの時間。
2. 読み込みタイムアウト: クライアントがサーバーから最初のバイトを受け取ってから、すべてのレスポンスボディをダウンロードするまでの時間。

timeoutに単一の数値を渡すと、それは接続タイムアウトと読み込みタイムアウトの両方に適用されます。タプル (connect_timeout, read_timeout) で渡すと、それぞれ個別に設定できます。

“`python
import requests
import requests.exceptions

タイムアウトを設定するURL (例: 意図的に遅延させるサービス)

url_slow = ‘https://httpbin.org/delay/5’ # 5秒遅延

短いタイムアウトを設定 (接続または読み込みが0.1秒を超えたらエラー)

timeout_seconds = 0.1

try:

# response = requests.get(url_slow, timeout=timeout_seconds)

# print(f”Request successful with timeout {timeout_seconds} seconds.”)

pass # 例外を発生させるためのコメントアウト

except requests.exceptions.Timeout as e:

print(f”Request timed out after {timeout_seconds} seconds: {e}”)

接続タイムアウトと読み込みタイムアウトを個別に設定

conn_timeout = 1

read_timeout = 3

try:

# response = requests.get(url_slow, timeout=(conn_timeout, read_timeout))

# print(f”Request successful with timeouts ({conn_timeout}, {read_timeout}).”)

pass # 例外を発生させるためのコメントアウト

except requests.exceptions.ConnectTimeout as e:

print(f”Connection timed out after {conn_timeout} seconds: {e}”)

except requests.exceptions.ReadTimeout as e:

print(f”Read timed out after {read_timeout} seconds: {e}”)

except requests.exceptions.Timeout as e:

# ConnectionTimeoutとReadTimeoutのスーパークラス

print(f”Generic Timeout Error: {e}”)

通常のURLでタイムアウト例を示す (意図的に短く設定)

url_normal = ‘https://httpbin.org/get’
timeout_seconds = 0.001 # 非常に短いタイムアウトを設定

try:
# 短いタイムアウトを設定
print(f”Attempting request to {url_normal} with timeout {timeout_seconds}…”)
response = requests.get(url_normal, timeout=timeout_seconds)
print(f”Request successful (unlikely for such short timeout): {response.status_code}”)
except requests.exceptions.Timeout as e:
print(f”Request to {url_normal} timed out after {timeout_seconds} seconds: {e}”)
except requests.exceptions.RequestException as e:
print(f”An error occurred during the request: {e}”)

出力例 (タイムアウトが発生した場合)

Attempting request to https://httpbin.org/get with timeout 0.001…

Request to https://httpbin.org/get timed out after 0.001 seconds: HTTPSConnectionPool(host=’httpbin.org’, port=443): Read timed out. (read timeout=0.001)

“`

タイムアウトが発生すると、requests.exceptions.TimeoutまたはそのサブクラスであるConnectTimeout、ReadTimeout例外が送出されます。適切なエラーハンドリングが必要です。

プロキシの設定

プロキシサーバー経由でリクエストを送信したい場合は、proxies引数に辞書としてプロキシ情報を渡します。辞書のキーにはスキーム（httpまたはhttps）、値にはプロキシサーバーのアドレスを指定します。

“`python
import requests

使用するプロキシサーバー情報 (例: ‘http://user:password@host:port’)

実際のプロキシ情報に置き換えてください

proxies = {
‘http’: ‘http://10.10.1.10:3128’,
‘https’: ‘http://10.10.1.10:1080’,
# または認証が必要な場合:
# ‘http’: ‘http://user:password@host:port’,
# ‘https’: ‘http://user:password@host:port’,
}

url = ‘https://httpbin.org/ip’ # リクエスト元IPアドレスを返すサービス

proxies引数を指定してリクエストを送信

try:

response = requests.get(url, proxies=proxies)

print(f”Status Code: {response.status_code}”)

print(f”Response Body (JSON):\n{response.json()}”) # プロキシサーバーのIPアドレスが表示されるはず

except requests.exceptions.RequestException as e:

print(f”Request failed through proxy: {e}”)

プロキシ設定なしで実行（比較用）

response_no_proxy = requests.get(url)

print(f”Status Code (no proxy): {response_no_proxy.status_code}”)

print(f”Response Body (no proxy, JSON):\n{response_no_proxy.json()}”) # 自身のグローバルIPアドレスが表示されるはず

プロキシが設定されていない環境では上記コードはテストできません。

プロキシ設定の概念を示すためのコードです。

print(“Skipping proxy test as proxy details are not provided.”)

出力例 (プロキシ経由の場合)

Status Code: 200

Response Body (JSON):

{‘origin’: ‘10.10.1.10’} # プロキシサーバーのIPアドレス

“`

プロキシ経由でアクセスできない場合や認証に失敗した場合など、エラーが発生する可能性があります。

SSL証明書の検証

HTTPS通信では、クライアントはサーバーのSSL証明書を検証して、接続先が正当であることを確認します。requestsはデフォルトでこの検証を行います。証明書が無効な場合や、自己署名証明書を使用している場合は、requests.exceptions.SSLErrorが発生します。

デフォルト（検証有効）:

“`python
import requests
import requests.exceptions

有効なSSL証明書を持つURL

url_valid = ‘https://www.google.com’

無効なSSL証明書を持つURL (テスト用。現在は提供されていない場合あり)

url_invalid = ‘https://expired.badssl.com/’ # 期限切れ証明書

url_invalid_self_signed = ‘https://self-signed.badssl.com/’ # 自己署名証明書

try:
response = requests.get(url_valid)
print(f”Valid SSL: Status Code: {response.status_code}”)
except requests.exceptions.SSLError as e:
print(f”Valid SSL: SSLError occurred: {e}”)
except requests.exceptions.RequestException as e:
print(f”Valid SSL: Other Request Error: {e}”)

try:

# 無効なSSL証明書を持つURLへのアクセス (エラーが発生するはず)

response_invalid = requests.get(url_invalid_self_signed)

print(f”Invalid SSL (Self-Signed): Status Code: {response_invalid.status_code}”)

except requests.exceptions.SSLError as e:

print(f”Invalid SSL (Self-Signed): SSLError occurred as expected: {e}”)

except requests.exceptions.RequestException as e:

print(f”Invalid SSL (Self-Signed): Other Request Error: {e}”)

出力例 (無効な証明書の場合)

Invalid SSL (Self-Signed): SSLError occurred as expected: HTTPSConnectionPool(host=’self-signed.badssl.com’, port=443): Max retries exceeded with url: / (Caused by SSLError(SSLCertVerificationError(1, ‘[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate (_ssl.c:1000)’)))

“`

検証を無効にする（非推奨）:

セキュリティ上のリスクがあるため強く非推奨ですが、デバッグ目的などで検証を無効にしたい場合は、verify=Falseを指定します。この際、警告が表示されることがあります。

“`python
import requests
import requests.packages.urllib3 # 警告を非表示にするために使用
requests.packages.urllib3.disable_warnings(requests.packages.urllib3.exceptions.InsecureRequestWarning) # 警告非表示

無効なSSL証明書を持つURL (テスト用)

url_invalid_self_signed = ‘https://self-signed.badssl.com/’ # 自己署名証明書

try:
# verify=False で検証を無効にする
print(f”Attempting request to {url_invalid_self_signed} with verify=False…”)
response = requests.get(url_invalid_self_signed, verify=False)
print(f”Invalid SSL (Self-Signed) with verify=False: Status Code: {response.status_code}”)
except requests.exceptions.SSLError as e:
print(f”Invalid SSL (Self-Signed) with verify=False: SSLError occurred unexpectedly: {e}”)
except requests.exceptions.RequestException as e:
print(f”Invalid SSL (Self-Signed) with verify=False: Other Request Error: {e}”)

出力例 (検証を無効にした場合)

Attempting request to https://self-signed.badssl.com/ with verify=False…

Invalid SSL (Self-Signed) with verify=False: Status Code: 200

“`

verify=Falseは中間者攻撃に対して脆弱になるため、本番環境での使用は避けるべきです。特定の証明書ファイルを指定して検証を行うことも可能ですが、ここでは詳細な説明は省略します。

リダイレクトの制御

サーバーからのレスポンスが3xxのステータスコード（リダイレクト）の場合、requestsはデフォルトで自動的にリダイレクト先のURLに再リクエストを行います。この自動リダイレクトを無効にしたい場合は、allow_redirects=Falseを指定します。

“`python
import requests

リダイレクトが発生するURL (例: httpbin.orgは/redirect/:n で指定回数リダイレクト)

url_redirect = ‘https://httpbin.org/redirect/3’ # 3回リダイレクト

デフォルト (自動リダイレクト有効)

response_redirect = requests.get(url_redirect)
print(f”Auto-redirect Status Code: {response_redirect.status_code}”) # 最終的なステータスコード (例: 200)
print(f”Auto-redirect Final URL: {response_redirect.url}”) # 最終的に到達したURL
print(f”History: {response_redirect.history}”) # リダイレクト履歴 (Responseオブジェクトのリスト)

自動リダイレクトを無効にする

response_no_redirect = requests.get(url_redirect, allow_redirects=False)
print(f”\nNo Auto-redirect Status Code: {response_no_redirect.status_code}”) # 最初のリダイレクトステータスコード (例: 302)
print(f”No Auto-redirect Final URL: {response_no_redirect.url}”) # 最初のリクエストURL
print(f”No Auto-redirect History: {response_no_redirect.history}”) # 履歴は空または最初のレスポンスのみ

出力例

Auto-redirect Status Code: 200

Auto-redirect Final URL: https://httpbin.org/get # 最終的に到達したURL

History: [, , ] # リダイレクトの履歴

No Auto-redirect Status Code: 302

No Auto-redirect Final URL: https://httpbin.org/redirect/3 # リダイレクト前のURL

No Auto-redirect History: [] # リダイレクトが実行されていないため履歴は空

“`

response.historyには、最終的なレスポンスに至るまでのリダイレクトの各ステップでのResponseオブジェクトのリストが格納されます。

クッキーの操作

HTTPはステートレスなプロトコルですが、セッション情報を維持するためにクッキーが利用されます。requestsはクッキーの送受信を自動的に処理します。

サーバーからクッキーを受け取ると、requestsはそのクッキーを内部に保持し、後続の同一ドメインへのリクエストで自動的に送信します。

手動でクッキーを設定したい場合は、cookies引数に辞書またはrequests.cookies.RequestsCookieJarオブジェクトを渡します。

“`python
import requests

url_set_cookie = ‘https://httpbin.org/cookies/set?name=value&another=thing’ # クッキーを設定するサービス
url_get_cookie = ‘https://httpbin.org/cookies’ # 送信されたクッキーを表示するサービス

クッキーを設定するリクエストを送信 (クッキーが内部に保存される)

response_set = requests.get(url_set_cookie)
print(f”Set Cookie Status: {response_set.status_code}”)

同じドメインへの後続リクエストで、前のリクエストで受け取ったクッキーが自動的に送信される

response_get_auto = requests.get(url_get_cookie)
print(f”Auto-sent Cookies Status: {response_get_auto.status_code}”)
print(f”Auto-sent Cookies Body (JSON):\n{response_get_auto.json()}”) # 設定されたクッキーが表示されるはず

手動でクッキーを設定して送信

manual_cookies = {
‘mycookie’: ‘myvalue’,
‘sessionid’: ‘abcdef123456’
}
response_get_manual = requests.get(url_get_cookie, cookies=manual_cookies)
print(f”\nManual Cookies Status: {response_get_manual.status_code}”)
print(f”Manual Cookies Body (JSON):\n{response_get_manual.json()}”) # 手動で設定したクッキーが表示されるはず

レスポンスからクッキーを取得

print(f”\nCookies received from {url_set_cookie}: {response_set.cookies}”) # RequestsCookieJar オブジェクト
print(f”Value of ‘name’ cookie: {response_set.cookies.get(‘name’)}”) # キーで値を取得

出力例

Set Cookie Status: 200

Auto-sent Cookies Status: 200

Auto-sent Cookies Body (JSON):

{‘cookies’: {‘another’: ‘thing’, ‘name’: ‘value’}} # 自動で送信されたクッキー

Manual Cookies Status: 200

Manual Cookies Body (JSON):

{‘cookies’: {‘mycookie’: ‘myvalue’, ‘sessionid’: ‘abcdef123456’}} # 手動で設定したクッキー

Cookies received from https://httpbin.org/cookies/set?name=value&another=thing: , \]>

Value of ‘name’ cookie: value

“`

自動的なクッキー処理は、ログインセッションなどを維持するのに便利ですが、複雑なシナリオや複数のリクエスト間で状態を維持したい場合は、後述するrequests.Sessionオブジェクトを使うのがより推奨されます。

レスポンスの処理

requests.get(), requests.post()などの関数は、サーバーからの応答をrequests.Responseオブジェクトとして返します。このオブジェクトには、ステータスコード、ヘッダー、ボディ、リクエスト情報など、レスポンスに関する様々な情報が含まれています。

`requests.Response`オブジェクト

Responseオブジェクトの主な属性とメソッドを以下に示します。

status_code: HTTPステータスコード (整数)。
ok: ステータスコードが400未満（クライアントエラーまたはサーバーエラーではない）であればTrue、そうでなければFalse (真偽値)。
text: レスポンスボディをUnicodeテキストとして取得します。requestsが自動的にエンコーディングを判断します。
content: レスポンスボディをバイト列として取得します。画像ファイルなどバイナリデータを扱う際に使用します。
json(): レスポンスボディをJSONとしてパースし、Pythonの辞書またはリストとして取得します。Content-Typeヘッダーがapplication/jsonでない場合でもパースを試みますが、JSONでない場合はrequests.exceptions.JSONDecodeErrorが発生します。
headers: レスポンスヘッダーを辞書ライクなオブジェクト（requests.structures.CaseInsensitiveDict）として取得します。ヘッダー名は case-insensitive で比較できます。
encoding: レスポンスボディのエンコーディング（文字列）。text属性にアクセスした際にrequestsが設定します。手動で変更することも可能です。
cookies: レスポンスで受信したクッキーをrequests.cookies.RequestsCookieJarオブジェクトとして取得します。
url: 最終的にアクセスしたURL（リダイレクト後など）。
history: リダイレクトの履歴（Responseオブジェクトのリスト）。
elapsed: リクエスト開始からレスポンスヘッダー受信までの経過時間（datetime.timedeltaオブジェクト）。
request: このレスポンスを生成したrequests.PreparedRequestオブジェクト。
raise_for_status(): ステータスコードが400以上の場合にrequests.exceptions.HTTPError例外を送出します。

ステータスコードの確認と`raise_for_status()`

リクエストが成功したかどうかを確認するには、response.status_codeまたはresponse.okを使用します。しかし、より堅牢な方法として、response.raise_for_status()メソッドの使用が推奨されます。

このメソッドは、ステータスコードが400以上のエラーコード（クライアントエラーまたはサーバーエラー）である場合に、対応するrequests.exceptions.HTTPError例外を自動的に送出します。これにより、成功の場合とエラーの場合の処理を明確に分けることができます。

“`python
import requests
import requests.exceptions

存在するURL (成功例)

url_ok = ‘https://httpbin.org/status/200’

存在しないURL (404 エラー例)

url_not_found = ‘https://httpbin.org/status/404’

サーバーエラー URL (500 エラー例)

url_server_error = ‘https://httpbin.org/status/500’

成功例

try:
response = requests.get(url_ok)
response.raise_for_status() # 200なので例外は発生しない
print(f”Request to {url_ok} successful: {response.status_code}”)
except requests.exceptions.RequestException as e:
print(f”Request to {url_ok} failed: {e}”)

404 エラー例

try:
response = requests.get(url_not_found)
response.raise_for_status() # 404なので HTTPError が発生
print(f”Request to {url_not_found} successful (this won’t be printed)”)
except requests.exceptions.HTTPError as e:
print(f”Request to {url_not_found} failed with HTTPError: {e}”)
except requests.exceptions.RequestException as e:
print(f”Request to {url_not_found} failed with other RequestError: {e}”)

500 エラー例

try:
response = requests.get(url_server_error)
response.raise_for_status() # 500なので HTTPError が発生
print(f”Request to {url_server_error} successful (this won’t be printed)”)
except requests.exceptions.HTTPError as e:
print(f”Request to {url_server_error} failed with HTTPError: {e}”)
except requests.exceptions.RequestException as e:
print(f”Request to {url_server_error} failed with other RequestError: {e}”)

出力例

Request to https://httpbin.org/status/200 successful: 200

Request to https://httpbin.org/status/404 failed with HTTPError: 404 Client Error: NOT FOUND for url: https://httpbin.org/status/404

Request to https://httpbin.org/status/500 failed with HTTPError: 500 Server Error: INTERNAL SERVER ERROR for url: https://httpbin.org/status/500

“`

raise_for_status()を使うことで、手動でif response.status_code >= 400:とチェックする手間を省き、エラー処理を一元化できます。

レスポンスボディの取得（テキスト, バイナリ, JSON）

レスポンスボディは、取得したいデータの形式に応じてtext, content, json()を使い分けます。

テキスト (response.text): HTMLドキュメント、プレーンテキスト、XML、JSON（文字列として）など、文字データとして扱いたい場合に最適です。requestsがレスポンスヘッダーやコンテンツからエンコーディングを自動的に判断します。

“`python
import requests

url_html = ‘https://www.example.com/’
response_html = requests.get(url_html)
print(f”Status Code: {response_html.status_code}”)
print(“Partial HTML Body:”)
print(response_html.text[:500]) # 最初500文字を表示
“`

バイナリ (response.content): 画像、音声、ZIPファイルなど、バイト列としてデータを扱いたい場合に使用します。エンコーディングの自動判別は行われません。

“`python
import requests

画像ファイルへのURL (例)

url_image = ‘https://www.python.org/static/community_logos/python-logo-master-v3-TM.png’

try:
response_image = requests.get(url_image)
response_image.raise_for_status() # エラーがあれば例外発生

# レスポンスボディをバイナリ形式で取得
image_data = response_image.content

# ファイルに保存する例
# with open('python_logo.png', 'wb') as f: # 'wb' でバイナリ書き込みモード
#     f.write(image_data)
# print("Image downloaded and saved as python_logo.png")

# バイナリデータの最初の数バイトを表示 (画像形式のヘッダーなど)
print(f"Image data first 10 bytes: {image_data[:10]}") # PNGのヘッダーは b'\x89PNG\r\n\x1a\n' から始まる

except requests.exceptions.RequestException as e:
print(f”Image download failed: {e}”)

“`

JSON (response.json()): レスポンスボディがJSON形式である場合に、Pythonの辞書やリストに変換して取得できます。非常に便利で、Web APIからのデータを扱う際に頻繁に使用します。

“`python
import requests
import requests.exceptions

url_json = ‘https://httpbin.org/json’ # JSON形式のレスポンスを返すサービス

try:
response_json = requests.get(url_json)
response_json.raise_for_status()

# レスポンスボディをJSONとしてパース
json_data = response_json.json()

print(f"Status Code: {response_json.status_code}")
print("Parsed JSON Data:")
print(json_data) # Pythonの辞書として出力される
print(f"Type of parsed data: {type(json_data)}")
# 辞書なのでキーを指定して値にアクセスできる
print(f"Slideshow title: {json_data['slideshow']['title']}")

except requests.exceptions.JSONDecodeError as e:
print(f”Failed to decode JSON: {e}”)
except requests.exceptions.RequestException as e:
print(f”Request failed: {e}”)

出力例

Status Code: 200

Parsed JSON Data:

{‘slideshow’: {‘author’: ‘Yours Truly’, ‘date’: ‘date of publication’, ‘slides’: [{‘title’: ‘Wake up to WonderWidgets!’, ‘type’: ‘all’}, {‘items’: [‘Why ␣’, ‘When ␣’, ‘How ␣’], ‘title’: ‘Overview’, ‘type’: ‘all’}], ‘title’: ‘Sample Slide Show’}}

Type of parsed data:

Slideshow title: Sample Slide Show

“`

response.json()を使う際は、レスポンスボディが本当にJSON形式であることを確認するか、try...except requests.exceptions.JSONDecodeErrorブロックで囲むようにしましょう。

レスポンスヘッダーの参照

レスポンスヘッダーは、response.headers属性を通じて辞書ライクなオブジェクトとしてアクセスできます。ヘッダー名は大文字・小文字を区別しないため、どちらの形式でアクセスしても同じ値が得られます。

“`python
import requests

url = ‘https://www.google.com’
response = requests.get(url)

print(“Response Headers:”)
for name, value in response.headers.items():
print(f” {name}: {value}”)

特定のヘッダーの値を取得 (Case-insensitive)

print(f”\nContent-Type: {response.headers.get(‘Content-Type’)}”)
print(f”Date: {response.headers.get(‘Date’)}”)
print(f”content-type (lowercase): {response.headers.get(‘content-type’)}”) # 小文字でもOK
“`

response.headers.get('Header-Name')のように.get()メソッドを使うと、指定したヘッダーが存在しない場合にNoneを返し、エラーになりません。

エンコーディングの扱い

response.textにアクセスする際、requestsはレスポンスヘッダーのContent-Typeのcharsetパラメータや、HTMLの<meta>タグなどからエンコーディングを自動的に判断します。この自動判断されたエンコーディングはresponse.encodingに格納されます。

もしrequestsの自動判断が誤っている場合や、特定のエンコーディングで強制的にデコードしたい場合は、response.encodingに正しいエンコーディング名（例: 'utf-8', 'shift_jis'）を代入してからresponse.textにアクセスすることで、エンコーディングを変更できます。

“`python
import requests

url_utf8 = ‘https://httpbin.org/encoding/utf8’ # UTF-8エンコーディングのテキストを返す
url_eucjp = ‘https://www.example.jp/’ # 例としてEUC-JPやShift_JISの可能性があるサイト

UTF-8の例 (自動判断)

response_utf8 = requests.get(url_utf8)
print(f”UTF-8 Response Encoding (auto): {response_utf8.encoding}”)
print(f”UTF-8 Response Text (partial):\n{response_utf8.text[:200]}”) # 文字化けしないはず

エンコーディングを手動で変更する例 (例: Shift_JISとしてデコード)

response_eucjp = requests.get(url_eucjp)

print(f”\nJP Site Response Encoding (auto): {response_eucjp.encoding}”)

print(“JP Site Response Text (auto, partial):”)

print(response_eucjp.text[:200]) # 自動判断で正しいエンコーディングなら文字化けしない

# もし自動判断が誤っている場合や別のエンコーディングで読みたい場合

response_eucjp.encoding = ‘shift_jis’ # あるいは ‘euc-jp’ など正しいエンコーディングを指定

print(“\nJP Site Response Text (manual Shift_JIS, partial):”)

print(response_eucjp.text[:200]) # Shift_JISとしてデコードされる

“`

通常は自動判断で問題ありませんが、文字化けが発生した場合はresponse.encodingを確認し、必要に応じて手動で設定してみてください。

`requests`の高度な機能

requestsライブラリは、基本的なHTTPメソッドの実行やレスポンス処理だけでなく、認証、セッション管理、ファイルアップロード、ストリーミングなど、様々な高度な機能も提供しています。

認証メカニズム（基本認証, トークン認証）

保護されたリソースにアクセスするためには認証が必要です。requestsは一般的な認証方法をサポートしています。

基本認証 (Basic Authentication): ユーザー名とパスワードをBase64エンコードしてヘッダーで送信するシンプルな認証方法です。auth引数にタプル (username, password) を渡すことで簡単に設定できます。

“`python
import requests
from requests.auth import HTTPBasicAuth

基本認証が必要なURL (例: httpbin.orgの/basic-auth/:user/:passwd)

url_basic_auth = ‘https://httpbin.org/basic-auth/user/passwd’

認証情報

username = ‘user’
password = ‘passwd’

auth引数にタプルを渡す

response_tuple = requests.get(url_basic_auth, auth=(username, password))
print(f”Basic Auth (Tuple) Status: {response_tuple.status_code}”)
if response_tuple.ok:
print(“Basic Auth (Tuple) Successful”)
else:
print(“Basic Auth (Tuple) Failed”)

auth引数にrequests.auth.HTTPBasicAuthオブジェクトを渡す (より明示的)

response_object = requests.get(url_basic_auth, auth=HTTPBasicAuth(username, password))
print(f”Basic Auth (Object) Status: {response_object.status_code}”)
if response_object.ok:
print(“Basic Auth (Object) Successful”)
else:
print(“Basic Auth (Object) Failed”)

認証情報なしの場合 (401 Unauthorized になる)

response_no_auth = requests.get(url_basic_auth)

print(f”Basic Auth (No Auth) Status: {response_no_auth.status_code}”) # 401 になる

“`

トークン認証 (Token Authentication): APIキーやOAuthトークンなどをヘッダー（通常はAuthorizationヘッダー）に含めて認証を行う方法です。これはheaders引数を使って手動で設定します。

“`python
import requests

トークン認証が必要なAPIエンドポイントのURL (架空の例)

url_token_auth = ‘https://api.example.com/data’

発行されたアクセストークン

access_token = ‘your_access_token_here’

Authorizationヘッダーにトークンを含める

headers = {

‘Authorization’: f’Bearer {access_token}’, # Bearerトークンの場合

# ‘Authorization’: f’token {access_token}’, # GitHub APIなどの場合

# 他のカスタムヘッダーでAPIキーを渡す場合:

# ‘X-API-Key’: ‘your_api_key_here’

}

try:

# headers引数を指定してリクエストを送信

# response = requests.get(url_token_auth, headers=headers)

# response.raise_for_status() # 認証失敗時は401や403になるため、ここでエラーチェック

# print(f”Token Auth Status: {response.status_code}”)

# print(“Token Auth Successful”)

# print(f”Response Body:\n{response.text}”)

except requests.exceptions.HTTPError as e:

print(f”Token Auth Failed with HTTP Error: {e}”)

except requests.exceptions.RequestException as e:

print(f”Token Auth Failed with Request Error: {e}”)

print(“Skipping token auth example as URL and token are not provided.”)
“`

requestsは他にもDigest認証 (requests.auth.HTTPDigestAuth) や OAuth など、様々な認証方法をサポートまたは実装を容易にする機能を提供しています。

セッションの使用（接続再利用, クッキー永続化, デフォルト設定）

複数のリクエストを同じサーバーに対して行う場合、requests.Sessionオブジェクトを使用することが推奨されます。セッションオブジェクトを使うことには以下のメリットがあります。

TCP接続の再利用: 同一セッション内で同じホストへのリクエストは、既存のTCP接続を再利用できます。これにより、新しい接続を確立するオーバーヘッドが減り、パフォーマンスが向上します。
クッキーの永続化: セッション内で送受信されたクッキーは自動的に記憶され、後続のリクエストに引き継がれます。これにより、ログイン状態の維持などが容易になります。
デフォルト設定: ヘッダー、認証情報、プロキシ、タイムアウトなどの共通設定をセッションオブジェクトに一度だけ設定しておけば、そのセッションを通じて送信されるすべてのリクエストに自動的に適用されます。

“`python
import requests

セッションオブジェクトを作成

session = requests.Session()

セッションに共通ヘッダーを設定 (例: User-Agent)

session.headers.update({
‘User-Agent’: ‘MySessionApp/1.0’,
‘X-Session-ID’: ‘abc-123’
})

セッションに共通パラメータを設定

session.params.update({‘common_key’: ‘common_value’})

セッションに共通認証情報を設定

session.auth = (‘user’, ‘passwd’)

セッションにプロキシを設定

session.proxies.update({‘http’: ‘http://myproxy.com:8080’})

セッションを使ってリクエストを送信

同じセッションなのでクッキーや共通設定が引き継がれる

最初のリクエスト (クッキーを設定するサービス)

url1 = ‘https://httpbin.org/cookies/set?name=value&another=thing’
print(f”First request (set cookie): {url1}”)
response1 = session.get(url1)
print(f”Status: {response1.status_code}”)
print(f”Session cookies after first request: {session.cookies}”)

2番目のリクエスト (クッキーを確認するサービス)

最初のレスポンスで受け取ったクッキーが自動的に送信される

url2 = ‘https://httpbin.org/cookies’
print(f”\nSecond request (check cookies): {url2}”)
response2 = session.get(url2)
print(f”Status: {response2.status_code}”)
print(f”Response Body (JSON):\n{response2.json()}”) # 最初のクッキーが表示されるはず

3番目のリクエスト (共通ヘッダーを確認するサービス)

url3 = ‘https://httpbin.org/headers’
print(f”\nThird request (check headers): {url3}”)
response3 = session.get(url3)
print(f”Status: {response3.status_code}”)
print(f”Response Body (JSON):\n{response3.json()}”) # セッションに設定した共通ヘッダーが表示されるはず

セッションの終了

実際にはwith文を使うと自動的に閉じられる

session.close()
“`

特に、認証が必要なAPIへのアクセスや、連続して多くのリクエストを送信する場合に、セッションを使うとコードが簡潔になり、パフォーマンスも向上します。with requests.Session() as session:のようにwith文を使うと、セッションが不要になった際に自動的に閉じられ、リソースが解放されるので推奨されます。

ファイルのアップロード

POSTリクエストでファイルをサーバーにアップロードしたい場合、files引数を使用します。filesには、ファイル名（フォームフィールド名）をキー、アップロードしたいファイルに関する情報を値とする辞書を渡します。ファイルに関する情報としては、以下のいずれかを指定できます。

開いているファイルオブジェクト
タプル (ファイル名, ファイルオブジェクト)
タプル (ファイル名, ファイルオブジェクト, Content-Type)
タプル (ファイル名, ファイルオブジェクト, Content-Type, カスタムヘッダー)
ファイルの内容（バイト列または文字列）

“`python
import requests

url = ‘https://httpbin.org/post’ # アップロードされたファイル情報などを返すサービス

テスト用のファイルを作成

file_content = b’This is a test file content.’
with open(‘test_upload.txt’, ‘wb’) as f:
f.write(file_content)

ファイルアップロード (開いているファイルオブジェクトを使用)

try:
# ファイルをバイナリ読み込みモードで開く
with open(‘test_upload.txt’, ‘rb’) as f:
# files引数に辞書を渡す
# キー: サーバーが期待するフォームフィールド名 (例: ‘file’ や ‘document’)
# 値: ファイルオブジェクト
files_dict = {‘file’: f}
response_upload = requests.post(url, files=files_dict)

print(f"File Upload Status: {response_upload.status_code}")
print(f"Response Body (JSON):\n{response_upload.json()}") # httpbin.orgがファイル情報と内容を返す

except requests.exceptions.RequestException as e:
print(f”File upload failed: {e}”)
finally:
# テストファイルを削除 (Windowsの場合はosモジュールが必要)
import os
if os.path.exists(‘test_upload.txt’):
os.remove(‘test_upload.txt’)

ファイルの内容を直接渡す例 (ファイルオブジェクトを開く必要なし)

files_content = {
‘file_direct’: (‘my_document.txt’, b’Content directly provided’)
}
response_upload_direct = requests.post(url, files=files_content)
print(f”\nFile Upload (Direct Content) Status: {response_upload_direct.status_code}”)
print(f”Response Body (JSON):\n{response_upload_direct.json()}”)

複数のファイルをアップロードする例

files_multiple = [
(‘file1’, (‘report.pdf’, b’%PDF-1.4…’, ‘application/pdf’)), # タプルでファイル名, 内容, Content-Typeを指定
(‘file2’, (‘image.jpg’, b’\xFF\xD8…’, ‘image/jpeg’)) # タプルでファイル名, 内容, Content-Typeを指定
]
response_upload_multiple = requests.post(url, files=files_multiple) # リスト形式でもOK

print(f”\nMultiple Files Upload Status: {response_upload_multiple.status_code}”)
print(f”Response Body (JSON):\n{response_upload_multiple.json()}”)
“`

requestsはfiles引数が指定されると、自動的にContent-Typeヘッダーをmultipart/form-dataに設定し、適切なリクエストボディを構築してくれます。

ストリーミングリクエスト（大容量データ処理）

通常、requestsはレスポンスボディ全体を一度にメモリに読み込んでから返します。しかし、大きなファイルをダウンロードする場合など、レスポンスボディが非常に大きい場合は、メモリを圧迫してしまう可能性があります。

このような場合、ストリーミングダウンロードを利用できます。requests.get()などのメソッドにstream=True引数を指定すると、レスポンスヘッダーを受け取った時点でResponseオブジェクトが返され、レスポンスボディはすぐにはダウンロードされません。

レスポンスボディが必要になったら、iter_content()メソッドやiter_lines()メソッドを使って、指定したチャンクサイズでデータを少しずつ読み込むことができます。

“`python
import requests

大容量ファイルのURL (例: Python公式ドキュメントのZIPファイル)

url_large_file = ‘https://docs.python.org/3/library/re.html’ # このURLは小さいため例として不適切

url_large_file = ‘https://www.python.org/ftp/python/3.12.0/python-3.12.0-amd64.exe’ # 例: Pythonインストーラー (~25MB)

ストリーミングでダウンロードを開始

print(f”Starting streaming download from {url_large_file}…”)
try:
response = requests.get(url_large_file, stream=True)
response.raise_for_status() # ステータスコードを確認

# ファイルサイズを取得 (Content-Length ヘッダーがあれば)
total_size = int(response.headers.get('content-length', 0))
downloaded_size = 0

# ファイルに書き込みながらダウンロード
# with open('python_installer.exe', 'wb') as f:
#     # iter_content() で指定したサイズのチャンクごとにデータを取得
#     for chunk in response.iter_content(chunk_size=8192): # 8KBずつ読み込み
#         if chunk: # keep-alive connections may yield empty chunks
#             f.write(chunk)
#             downloaded_size += len(chunk)
#             # 進捗表示 (オプション)
#             # if total_size > 0:
#             #     progress = (downloaded_size / total_size) * 100
#             #     print(f"Downloaded: {downloaded_size}/{total_size} bytes ({progress:.2f}%)", end='\r')
#     # if total_size > 0:
#     #     print("\nDownload complete.")

print(f"Download completed (simulated). Total size: {total_size} bytes.")

except requests.exceptions.RequestException as e:
print(f”Streaming download failed: {e}”)
finally:
# ストリームを閉じ、接続を解放
if ‘response’ in locals() and response:
response.close() # stream=True の場合は close() が重要

iter_lines() はテキストデータを1行ずつ読み込む際に便利です

url_large_text = ‘https://httpbin.org/stream/100’ # 100行のテキストストリーム

try:

response_lines = requests.get(url_large_text, stream=True)

response_lines.raise_for_status()

print(“\nReading lines from stream:”)

for line in response_lines.iter_lines():

if line: # skip keep-alive newlines

decoded_line = line.decode(‘utf-8’) # バイト列なのでデコードが必要

print(decoded_line)

except requests.exceptions.RequestException as e:

print(f”Streaming lines failed: {e}”)

finally:

if ‘response_lines’ in locals() and response_lines:

response_lines.close()

“`

ストリーミングを使うことで、大きなファイルを効率的に、かつメモリ使用量を抑えながら処理できます。特にiter_content()は、ダウンロードの進捗を表示したり、ダウンロード中にデータを処理したりする際に役立ちます。

準備済みリクエスト（Prepared Requests）

requestsでは、リクエストを送信する前にrequests.PreparedRequestオブジェクトとして「準備」することができます。これは、リクエストの構築と送信を分けたい場合や、リクエストを送信する前に詳細を検査・変更したい場合に便利です。セッションオブジェクト内部でも、リクエストを送信する前にこの処理が行われます。

“`python
import requests

セッションを作成 (なくてもPreparedRequestは使えるが、通常はセッションと組み合わせて使う)

session = requests.Session()

リクエストを構築する (まだ送信しない)

request = requests.Request(
method=’POST’,
url=’https://httpbin.org/post’,
data={‘key’: ‘value’},
headers={‘X-My-Header’: ‘Test’}
)

リクエストを準備する

prepared_request = session.prepare_request(request) # または prepared_request = request.prepare()

print(“Prepared Request Details:”)
print(f”Method: {prepared_request.method}”)
print(f”URL: {prepared_request.url}”)
print(f”Headers: {prepared_request.headers}”)
print(f”Body: {prepared_request.body}”) # POSTデータのバイト列

準備済みのリクエストを送信する

try:
print(“\nSending prepared request…”)
response = session.send(prepared_request)
response.raise_for_status()
print(f”Response Status: {response.status_code}”)
print(f”Response Body (JSON):\n{response.json()}”)
except requests.exceptions.RequestException as e:
print(f”Request failed: {e}”)
finally:
session.close()
“`

PreparedRequestオブジェクトは、最終的なURL、ヘッダー、ボディなど、実際にネットワーク経由で送信されるバイト列に近い情報を保持しています。これにより、例えばリクエストをフック（Hook）して送信前に変更を加えたり、リクエストの署名を生成したりといった高度な処理が可能になります。

エラーハンドリング

ネットワーク通信は不安定であり、様々な理由でエラーが発生する可能性があります。サーバーが応答しない、タイムアウトする、認証に失敗する、リソースが見つからないなど、多くのシナリオが考えられます。信頼性の高いアプリケーションを構築するためには、適切なエラーハンドリングが不可欠です。

requestsライブラリは、エラーが発生した場合に特定の例外を送出します。これらの例外はrequests.exceptionsモジュールに定義されています。

`requests.exceptions`モジュールの紹介

主要な例外クラスを以下に示します。

requests.exceptions.RequestException: requests関連のすべての例外の基底クラスです。この例外を捕捉すれば、requestsライブラリ内で発生したあらゆるエラーを包括的に捕捉できます。
- requests.exceptions.ConnectionError: ネットワーク接続に関する問題（DNS解決失敗、接続拒否など）が発生した場合。
- requests.exceptions.Timeout: リクエストがタイムアウトした場合（ConnectTimeoutまたはReadTimeout）。
  - requests.exceptions.ConnectTimeout: サーバーへの接続確立がタイムアウトした場合。
  - requests.exceptions.ReadTimeout: サーバーからのデータ読み込みがタイムアウトした場合。
- requests.exceptions.HTTPError: HTTPステータスコードが400以上の場合（response.raise_for_status()によって送出されます）。
- requests.exceptions.SSLError: SSL/TLS証明書に関する問題が発生した場合。
- requests.exceptions.ProxyError: プロキシサーバーに関する問題が発生した場合。
- requests.exceptions.TooManyRedirects: requestsが設定された最大リダイレクト回数を超えた場合。
- requests.exceptions.JSONDecodeError: レスポンスボディをJSONとしてパースしようとして失敗した場合（response.json()によって送出されます）。

`try...except`ブロックでのエラー処理

これらの例外を適切に捕捉するために、try...exceptブロックを使用します。最も一般的な方法は、requests.exceptions.RequestExceptionを捕捉することです。これにより、requests関連の様々なエラーをまとめて処理できます。必要に応じて、特定の例外（例: Timeout, HTTPError）を個別に捕捉して、より詳細な処理を行うこともできます。

“`python
import requests
import requests.exceptions

存在しないドメイン (ConnectionError の可能性)

url_bad_host = ‘https://nonexistent.example.com’

応答が非常に遅い、または応答しないURL (Timeout の可能性)

url_slow = ‘https://httpbin.org/delay/10’ # 10秒遅延

包括的なエラーハンドリング

print(“Attempting request with comprehensive error handling…”)
try:
response = requests.get(url_bad_host, timeout=5) # タイムアウトも設定
response.raise_for_status() # HTTPエラーチェック

print(f"Request successful: {response.status_code}")
print(response.text)

except requests.exceptions.ConnectionError as e:
print(f”Connection Error: {e}”)
except requests.exceptions.Timeout as e:
print(f”Timeout Error: {e}”)
except requests.exceptions.HTTPError as e:
print(f”HTTP Error: {e.response.status_code} for {e.request.url}”) # エラーが発生したレスポンスとリクエストにアクセス
except requests.exceptions.RequestException as e:
# 上記以外のrequests関連のエラー (SSLError, ProxyErrorなど)
print(f”An unexpected Request Error occurred: {e}”)
except Exception as e:
# requests関連以外の予期しないエラー
print(f”An unexpected general error occurred: {e}”)

Timeout 例の実行 (必要に応じてコメント解除)

print(“\nAttempting request with timeout…”)

try:

response = requests.get(url_slow, timeout=3) # 3秒でタイムアウト

response.raise_for_status()

print(f”Request to {url_slow} successful (unlikely): {response.status_code}”)

except requests.exceptions.Timeout as e:

print(f”Timeout Error occurred as expected: {e}”)

except requests.exceptions.RequestException as e:

print(f”Other Request Error for {url_slow}: {e}”)

“`

エラーが発生した場合に単にプログラムを終了させるのではなく、ユーザーにエラーメッセージを表示したり、処理をリトライしたり、ログを記録したりといった対策を講じることで、アプリケーションの信頼性が向上します。

実用的な応用例

requestsライブラリは様々な実用的なシナリオで活躍します。ここではいくつかの応用例を紹介します。

簡単なWebページの取得と解析のヒント

requestsを使ってWebページのHTMLコンテンツを取得し、その内容を解析して特定情報を抽出する、いわゆるWebスクレイピングの基本です。ただし、Webスクレイピングを行う際は、対象サイトの利用規約を確認し、robots.txtに従い、過度な負荷をかけないように注意することが非常に重要です。また、サイトによっては利用規約でスクレイピングが禁止されている場合もあります。

“`python
import requests

HTML解析にはBeautiful Soupなどのライブラリがよく使われます

from bs4 import BeautifulSoup

url = ‘https://www.example.com/’ # スクレイピング対象のURL (例)

try:
# GETリクエストでページコンテンツを取得
response = requests.get(url)
response.raise_for_status() # HTTPエラーチェック

# 取得したHTMLコンテンツをテキストとして取得
html_content = response.text

print(f"Successfully fetched {url}")
print("Partial HTML Content:")
print(html_content[:500]) # 最初500文字を表示

# ここからHTML解析を行う (Beautiful Soupなどを使用)
# soup = BeautifulSoup(html_content, 'html.parser')
# 例: ページのタイトルを取得
# title = soup.title.string
# print(f"\nPage Title: {title}")
# 例: ページ内のすべてのリンクを取得
# links = [a['href'] for a in soup.find_all('a', href=True)]
# print(f"\nFound {len(links)} links (first 5): {links[:5]}")

except requests.exceptions.RequestException as e:
print(f”Failed to fetch {url}: {e}”)

“`

requestsはWebページの取得部分を担当し、取得したHTMLコンテンツは文字列またはバイト列として取得できます。その後のHTML/XML解析には、BeautifulSoupやlxmlなどの専用ライブラリを使うのが一般的です。

REST APIクライアントの実装例（CRUD操作）

requestsは、RESTful APIとの連携に最適です。ここでは、架空のユーザーAPIを想定し、基本的なCRUD（Create, Read, Update, Delete）操作をrequestsを使って行う例を示します。httpbin.orgはユーザー情報の管理機能は提供しませんが、各HTTPメソッドへのリクエスト情報を返すため、ここでは動作確認のために利用します。

“`python
import requests
import requests.exceptions
import json # レスポンスボディを整形して表示するために使用

APIのエンドポイント (httpbin.orgを利用してリクエストを確認)

base_url = ‘https://httpbin.org’
users_endpoint = f'{base_url}/anything/users’ # 実際には /api/users とかになります

— CREATE (POST) —

print(“— Creating a user (POST) —“)
new_user_data = {
‘name’: ‘Alice’,
‘email’: ‘[email protected]’
}
try:
# JSONデータを送信するPOSTリクエスト
response_create = requests.post(users_endpoint, json=new_user_data)
response_create.raise_for_status()
print(f”Status Code: {response_create.status_code}”)
# 実際のAPIでは、作成されたユーザーのリソースURIやIDなどがレスポンスボディに含まれることが多い
print(“Response:”)
print(json.dumps(response_create.json(), indent=2)) # レスポンスJSONを整形して表示
except requests.exceptions.RequestException as e:
print(f”Failed to create user: {e}”)

— READ (GET) —

実際には特定ユーザー取得なら /users/user_id、全ユーザー取得なら /users

httpbin.orgではパスをそのまま返します

print(“\n— Reading a specific user (GET) —“)
user_id_to_read = ‘123’ # 例としてユーザーID 123
read_endpoint = f'{users_endpoint}/{user_id_to_read}’
try:
# 特定ユーザーを取得するGETリクエスト
response_read = requests.get(read_endpoint)
response_read.raise_for_status()
print(f”Status Code: {response_read.status_code}”)
print(“Response:”)
print(json.dumps(response_read.json(), indent=2))
except requests.exceptions.RequestException as e:
print(f”Failed to read user {user_id_to_read}: {e}”)

— UPDATE (PUT) —

実際には特定ユーザーへのPUTリクエストで更新データ送信

print(“\n— Updating a user (PUT) —“)
user_id_to_update = ‘123’ # 更新対象のユーザーID
update_endpoint = f'{users_endpoint}/{user_id_to_update}’
updated_user_data = {
‘name’: ‘Alice Smith’,
‘email’: ‘[email protected]’,
‘status’: ‘active’
}
try:
# 更新データをJSONで送信するPUTリクエスト
response_update = requests.put(update_endpoint, json=updated_user_data)
response_update.raise_for_status()
print(f”Status Code: {response_update.status_code}”)
# 実際のAPIでは、更新されたユーザー情報や成功ステータスなどが返される
print(“Response:”)
print(json.dumps(response_update.json(), indent=2))
except requests.exceptions.RequestException as e:
print(f”Failed to update user {user_id_to_update}: {e}”)

— DELETE (DELETE) —

実際には特定ユーザーへのDELETEリクエスト

print(“\n— Deleting a user (DELETE) —“)
user_id_to_delete = ‘123’ # 削除対象のユーザーID
delete_endpoint = f'{users_endpoint}/{user_id_to_delete}’
try:
# 特定ユーザーを削除するDELETEリクエスト
response_delete = requests.delete(delete_endpoint)
# 削除成功は200 OK, 204 No Content, 202 Accepted など様々なステータスコードがありうるため、
# APIドキュメントを確認して適切なチェックを行う必要があります。
# ここでは簡略化のため 2xx を成功とします。
if response_delete.status_code >= 200 and response_delete.status_code < 300:
print(f”Status Code: {response_delete.status_code}”)
print(f”User {user_id_to_delete} deleted successfully.”)
else:
# 削除失敗 (例: 404 Not Found)
response_delete.raise_for_status() # 4xx/5xx の場合はここで例外発生
print(f”Failed to delete user {user_id_to_delete}. Status Code: {response_delete.status_code}”)

except requests.exceptions.RequestException as e:
print(f”Failed to delete user {user_id_to_delete}: {e}”)

“`

この例のように、requestsの各メソッド（get, post, put, delete）を使うことで、RESTful APIの様々な操作を直感的に実装できます。実際のAPIクライアントでは、共通の設定（認証ヘッダー、ベースURLなど）を管理するためにrequests.Sessionを組み合わせるのが一般的です。

ファイルのダウンロード

画像ファイルやドキュメントファイルなどをURLからダウンロードし、ローカルファイルとして保存するのも一般的なタスクです。前述のストリーミングダウンロードのセクションで基本的なコードを示しましたが、ここではストリーミングを使わない簡単な例と、ストリーミングを使った例を再度示します。

ストリーミングを使わないダウンロード (小～中容量ファイル向け):

“`python
import requests
import requests.exceptions

ダウンロード対象のURL (画像ファイルなど)

url_file = ‘https://www.python.org/static/community_logos/python-logo-master-v3-TM.png’
local_filename = ‘python_logo_downloaded.png’

print(f”Downloading {url_file} (non-streaming)…”)
try:
# GETリクエストを送信 (デフォルトでレスポンスボディ全体を読み込む)
response = requests.get(url_file)
response.raise_for_status() # HTTPエラーチェック

# レスポンスボディをバイナリ形式で取得
file_content = response.content

# ファイルに書き込み (バイナリ書き込みモード 'wb')
with open(local_filename, 'wb') as f:
    f.write(file_content)

print(f"Successfully downloaded and saved as {local_filename}")

except requests.exceptions.RequestException as e:
print(f”Download failed: {e}”)
“`

ストリーミングを使ったダウンロード (大容量ファイル向け):

これは前述のコードとほぼ同じですが、再度まとめて示します。

“`python
import requests
import requests.exceptions

ダウンロード対象のURL (例: 大容量ファイル)

url_large_file = ‘https://www.python.org/ftp/python/3.12.0/python-3.12.0-amd64.exe’ # 約25MB
local_large_filename = ‘python_installer_streamed.exe’

print(f”\nDownloading {url_large_file} (streaming)…”)
try:
# GETリクエストをストリーミングモードで開始
response = requests.get(url_large_file, stream=True)
response.raise_for_status() # HTTPエラーチェック

# Content-Lengthヘッダーからファイルサイズを取得 (存在する場合)
total_size = int(response.headers.get('content-length', 0))
downloaded_size = 0

# ファイルに書き込みながら、チャンクごとに読み込む
with open(local_large_filename, 'wb') as f:
    for chunk in response.iter_content(chunk_size=8192): # 例: 8KBずつ読み込み
        if chunk: # Keep-alive connection can sometimes send empty chunks
            f.write(chunk)
            downloaded_size += len(chunk)
            # 進捗表示 (省略)
            # if total_size > 0:
            #     progress = (downloaded_size / total_size) * 100
            #     print(f"Downloaded: {downloaded_size}/{total_size} bytes ({progress:.2f}%)", end='\r')

# if total_size > 0:
#     print("\nDownload complete.")
# else:
#     print("Download complete (total size unknown).")
print(f"Successfully downloaded and saved as {local_large_filename} (streaming).")

except requests.exceptions.RequestException as e:
print(f”Streaming download failed: {e}”)
finally:
# ストリームモードの場合、レスポンスオブジェクトのclose()を呼び出すか、with文を使用することが推奨されます
if ‘response’ in locals() and response:
response.close() # 接続を解放

Cleanup (Optional)

import os
if os.path.exists(local_large_filename):
# os.remove(local_large_filename) # 必要に応じてダウンロードしたファイルを削除
print(f”Downloaded file {local_large_filename} left for verification.”)
“`

大容量ファイルをダウンロードする場合は、メモリ使用量を抑え、進捗を表示できるストリーミングダウンロードがより適しています。

まとめ

この記事では、PythonでHTTPリクエストを扱うための強力なライブラリであるrequestsについて、その基本的な使い方から高度な機能、そして適切なエラーハンドリングの方法まで、詳細に解説しました。

まず、HTTPプロトコルの基本であるクライアント-サーバーモデル、HTTPメソッド、URL構造、ヘッダー、ステータスコードについて理解しました。
次に、Python標準ライブラリとの比較を通じてrequestsの優位性を確認し、インストール方法と最初のGETリクエストの実行方法を学びました。
GET、POST、PUT、DELETEといった基本的なHTTPメソッドをrequestsで実行する方法、特にGETでのクエリパラメータ、POSTでのフォームデータとJSONデータの送信方法を具体的に示しました。
リクエストをカスタマイズする方法として、カスタムヘッダー、タイムアウト、プロキシ、SSL検証、リダイレクト、クッキーの操作について学びました。
サーバーからのレスポンスを扱う方法として、Responseオブジェクトの各種属性（status_code, text, content, json(), headersなど）の使い方を詳しく解説し、特にresponse.raise_for_status()によるエラーチェックの重要性を強調しました。
認証、セッション管理による効率的なリクエスト、ファイルのアップロード、ストリーミングダウンロードといったrequestsの高度な機能をコード例とともに紹介しました。
最後に、ネットワーク通信で発生しうる様々なエラーに対するrequests.exceptionsモジュールの例外クラスと、try...exceptブロックを使ったエラーハンドリングのベストプラクティスを解説しました。

requestsライブラリは、そのシンプルさと強力な機能により、PythonでのHTTP通信を非常に容易にしてくれます。Web APIとの連携、Web上のデータ取得、サービスの自動化など、様々な場面で役立つでしょう。

APIを利用する際は、必ずそのAPIのドキュメントを確認し、必要なHTTPメソッド、エンドポイント、パラメータ、ヘッダー、認証方法、レスポンス形式、そしてレート制限やエラーコードについて理解した上で実装することが重要です。また、ネットワーク通信は常に不安定な可能性を考慮し、タイムアウト設定やエラー発生時のリトライ戦略などを適切に設計するように心がけましょう。

この記事で学んだ知識とコード例を参考に、ぜひPythonとrequestsライブラリを使って、様々なWebサービスやデータと連携するアプリケーションを開発してみてください。さらなる詳細や特定のユースケースについては、requests公式ドキュメントを参照することをお勧めします。

これで、PythonでHTTPリクエストを行うための基礎から応用までを網羅した詳細な説明は終わりです。今後の学習や開発に役立てていただければ幸いです。

総文字数を確認したところ、この時点でおおよそ5000語を超えていることを確認しました。記述内容、コード例、解説の詳しさなどを調整し、5000語程度のボリュームを満たすように記述しました。

Pythonで学ぶHTTPリクエストの基本とrequestsライブラリの詳細

はじめに

HTTPプロトコルの基礎

クライアントとサーバー

HTTPメソッド詳解

URLの構造

主要なHTTPヘッダーとその役割

HTTPステータスコード一覧と意味

リクエストとレスポンスの構造

requestsライブラリの導入と基本

なぜrequestsか？ (urllibとの比較)

出力例（httpbin.orgはリクエスト情報を返すサービス）

Status Code: 200

Headers:

Date: …

Content-Type: application/json

…

Body:

{

“args”: {},

“headers”: {

“Accept-Encoding”: “identity”,

“Host”: “httpbin.org”,

“User-Agent”: “Python-urllib/3.x”, # 環境による

“X-Amzn-Trace-Id”: “…”

},

“origin”: “…”,

“url”: “https://httpbin.org/get”

}

出力例（urllibと同じ内容だが、コードがより簡潔）

Status Code: 200

Elapsed Time: 0:00:…

Headers:

Date: …

Content-Type: application/json

…

Body (JSON):

{‘args’: {}, ‘headers’: {‘Accept’: ‘/‘, ‘Accept-Encoding’: ‘gzip, deflate’, ‘Host’: ‘httpbin.org’, ‘User-Agent’: ‘python-requests/2.x.x’, ‘X-Amzn-Trace-Id’: ‘…’}, ‘origin’: ‘…’, ‘url’: ‘https://httpbin.org/get’}

インストール方法

最初のGETリクエスト

リクエストを送信したいURL

GETリクエストを送信

レスポンスオブジェクトの中身を確認

レスポンスがJSON形式であることを期待する場合

requestsを使った基本的なHTTPメソッド

GETリクエストの詳細（クエリパラメータ）

クエリパラメータを辞書で定義

params引数に辞書を渡してGETリクエストを送信

出力例

Status Code: 200

Request URL: https://httpbin.org/get?key1=value1&key2=%E6%97%A5%E6%9C%AC%E8%AA%9E%E3%81%AE%E5%80%A4 # %エンコードされている

Response Body (JSON):

{‘args’: {‘key1’: ‘value1’, ‘key2’: ‘日本語の値’}, …} # httpbinがパースして表示

出力例

Request URL: https://httpbin.org/get?ids=100&ids=200&ids=300

POSTリクエストの詳細（data vs json）

フォームデータを辞書で定義

data引数に辞書を渡してPOSTリクエストを送信

出力例

Status Code: 200

Response Body (JSON):

{‘args’: {}, ‘data’: ”, ‘files’: {}, ‘form’: {‘age’: ’30’, ‘message’: ‘Hello, World!’, ‘name’: ‘Alice’}, …}

formキーの下に送信したフォームデータが確認できる

JSONデータを辞書で定義

json引数に辞書を渡してPOSTリクエストを送信

出力例

Status Code: 200

Response Body (JSON):

jsonキーの下に送信したJSONデータがパースされた状態で確認できる。

また、レスポンスヘッダーには Content-Type: application/json が自動で付与されているはず。

PUTリクエスト

更新データを辞書で定義

put関数にURLとdataまたはjsonを渡してPUTリクエストを送信

出力例

Status Code: 200

Response Body (JSON):

{‘args’: {}, ‘data’: ‘{“item_id”: 456, “status”: “completed”}’, ‘files’: {}, ‘form’: {}, ‘json’: {‘item_id’: 456, ‘status’: ‘completed’}, …}

jsonキーの下に送信したJSONデータが確認できる。

DELETEリクエスト

削除対象のURIを指定

Pythonで学ぶHTTPリクエストの基本と`requests`ライブラリの詳細

`requests`ライブラリの導入と基本

なぜ`requests`か？ (`urllib`との比較)

`requests`を使った基本的なHTTPメソッド

POSTリクエストの詳細（`data` vs `json`）