ネットワーククライアント
Tip
この記事を読む必要があるのは:出力(outbound)の HTTP / WebSocket リクエストが必要な場合。必要ない場合はスキップしても、他の機能への影響はありません。
ErisPulse は、HTTP リクエスト、WebSocket 接続、および接続プール管理を統合した一貫したネットワーククライアントを提供しています。モジュールやアダプタは、このクライアントを優先的に使用する必要があります。aiohttp / httpx / requests などの外部ライブラリを直接インポートしてはいけません。
概要
ネットワーククライアントの主な機能は以下の通りです:
- 統一されたインターフェース:
get/post/put/delete/patch/requestメソッドを提供 - WebSocketクライアント:
ws_connectでクライアントWebSocket接続を確立 - 自動ログ:すべてのリクエストに対して自動的にログと統計情報を記録
- ライフサイクル統合:リクエストごとに
client.requestライフサイクルイベントがトリガーされ、WS接続はclient.ws.connectイベントを発生 - リトライサポート:自動リトライの回数と間隔を設定可能
- タイムアウト制御:接続タイムアウトとリクエストタイムアウトを個別に設定
- 接続プールの再利用:aiohttp.ClientSession に基づく接続プール管理
- 例外体系:aiohttpの例外をErisPulseの例外(ClientError体系)に自動変換
速習
HTTPリクエスト
from ErisPulse.Core import client
# GETリクエスト
resp = await client.get("https://httpbin.org/get")
data = await resp.json()
print(resp.status) # 200
# POSTリクエスト
resp = await client.post(
"https://httpbin.org/post",
json={"key": "value"},
)
data = await resp.json()
WebSocket接続
from ErisPulse import client # 2.10+ からのルートインポート(ErisPulse.Core.client は深階層でも互換性あり)
ws = await client.ws_connect("wss://example.com/ws")
async for text in ws.iter_text():
await ws.send_text(f"Echo: {text}")
出力接続の自動プール登録(2.10+)
ws_connect で確立された接続はデフォルトでフレームワークの接続プールに登録されます(track=False で無効化可能):
connections.list(owner=...) で確認でき、その接続にブロードキャストが可能。接続が閉じられたり、リモートが切断された場合、自動的に登録解除されます。
モジュールのアンロード / アダプターの停止時に、フレームワークがその名下のすべての出力接続を一括で閉じるため、リークを防ぎます。
from ErisPulse import client, connections
ws = await client.ws_connect("wss://example.com/ws")
print(ws.id, ws.owner) # 登録済み:接続IDと所有者
# ownerコンテキストが使用できない場合(例:ツールスレッドのコールバック)は、明示的に所有者を指定し、アンロード時に自動回収されるようにする:
ws2 = await client.ws_connect("wss://example.com/ws2", owner="MyAdapter")
接続プールとブロードキャストの詳細は接続プールとブロードキャストを参照してください。
HttpResponse
すべてのリクエストメソッドは HttpResponse オブジェクトを返します:
from ErisPulse.Core import client
resp = await client.get("https://httpbin.org/get")
resp.status # int - HTTPステータスコード (例: 200, 404)
resp.reason # str | None - ステータス説明 (例: "OK")
resp.headers # レスポンスヘッダー (大文字小文字を区別しない)
resp.content_type # str | None - Content-Type
resp.url # 最終URL (リダイレクトにより変更される可能性がある)
resp.raw # 低レベルの元のレスポンスオブジェクト (現在は aiohttp.ClientResponse)
# レスポンスボディの読み取り
body = await resp.read() # bytes
text = await resp.text() # str
data = await resp.json() # JSONを解析
text = await resp.text("gbk") # 指定したエンコーディング
リクエストメソッド
GET
from ErisPulse.Core import client
resp = await client.get(
"https://api.example.com/users",
params={"page": "1", "limit": "10"},
headers={"Authorization": "Bearer token"},
)
POST
from ErisPulse.Core import client
# JSONリクエストボディ
resp = await client.post(
"https://api.example.com/users",
json={"name": "Alice", "age": 30},
)
# フォームリクエストボディ
resp = await client.post(
"https://api.example.com/login",
data={"username": "admin", "password": "123"},
)
# バイナリデータ
resp = await client.post(
"https://api.example.com/upload",
data=b"raw bytes",
headers={"Content-Type": "application/octet-stream"},
)
# ファイルアップロード (filesパラメータを使用、aiohttpをインポートする必要はない)
# 形式: {フィールド名: ファイルオブジェクト/bytes/(filename, file)/(filename, file, content_type)}
resp = await client.post(
"https://api.example.com/upload",
data={"description": "プロフィール画像"}, # 任意: 通常のフォームフィールドも同時に送信可能
files={
"file": ("photo.png", open("photo.png", "rb"), "image/png"),
},
)
# 簡略化された書き方: ファイルオブジェクトを直接渡す
resp = await client.post(
"https://api.example.com/upload",
files={"file": open("photo.png", "rb")},
)
# メモリ内のデータを直接アップロード (ファイルに落とす必要はない)
import io
resp = await client.post(
"https://api.example.com/upload",
files={"file": ("data.txt", io.BytesIO(b"file content"), "text/plain")},
)
PUT / DELETE / PATCH
from ErisPulse.Core import client
resp = await client.put("https://api.example.com/users/1", json={"name": "Bob"})
resp = await client.delete("https://api.example.com/users/1")
resp = await client.patch("https://api.example.com/users/1", json={"age": 31})
一般的なrequest
from ErisPulse.Core import client
resp = await client.request(
"OPTIONS",
"https://api.example.com/resource",
headers={"Origin": "https://example.com"},
)
パラメータの説明
HTTPリクエストパラメータ
| パラメータ | 型 | 説明 |
|---|---|---|
url |
str |
リクエストURL |
params |
dict[str, str] |
クエリパラメータ (オプション) |
headers |
dict[str, str] |
追加のリクエストヘッダー (オプション) |
data |
Any |
リクエストボディ (フォームまたはバイナリデータ) (オプション) |
json |
Any |
JSONリクエストボディ (オプション) |
files |
dict[str, Any] |
ファイルアップロードフィールド (オプション、multipart/form-dataを自動構築) |
timeout |
float |
今回のリクエストのタイムアウト (秒) (オプション、デフォルト値を上書き) |
max_retries |
int |
今回の最大リトライ回数 (オプション、デフォルト値を上書き) |
ws_connect パラメータ
| パラメータ | 型 | 説明 |
|---|---|---|
url |
str |
WebSocketサーバーのURL |
headers |
dict[str, str] |
追加のリクエストヘッダー (オプション) |
heartbeat |
float |
ハートビートの間隔 (秒) (オプション) |
タイムアウトとリトライ
from ErisPulse.Core import Client
# タイムアウトを設定したクライアントを作成
client = Client(
timeout=60, # リクエスト全体のタイムアウト 60秒
connect_timeout=5, # 接続のタイムアウト 5秒
max_retries=3, # 失敗時に自動リトライ 3回
retry_delay=2, # リトライ間隔 2秒
)
# 単一のリクエストでタイムアウトを上書き
resp = await client.get("https://slow-api.example.com/data", timeout=120)
Note
クライアントクラスは 2.8.0 から Client に名前が変更されました(sdk.client の属性名は変更されません);HttpClient は旧名として互換性の別名として残されています。古いコードは変更する必要はありません。
デフォルトヘッダーのカスタマイズ
client = Client(
headers={
"Authorization": "Bearer token",
"X-App-Id": "my-app",
},
user_agent="MyBot/1.0",
)
リクエスト統計
from ErisPulse.Core import client
# 統計情報の取得
stats = client.stats
# {"total_requests": 42, "total_errors": 1, "total_bytes_sent": 0, "total_bytes_received": 0}
# 統計情報のリセット
client.reset_stats()
ライフサイクルイベント
HTTPリクエストイベント
リクエストが完了するたびに client.request イベントがトリガーされ、監視に使用できます:
from ErisPulse.Core import lifecycle
@lifecycle.on("client.request")
async def on_request(event_data):
print(f"{event_data['method']} {event_data['url']} -> {event_data['status']} ({event_data['elapsed']}s)")
WebSocket接続イベント
WebSocket接続が確立されたたびに client.ws.connect イベントがトリガーされます:
from ErisPulse.Core import lifecycle
@lifecycle.on("client.ws.connect")
async def on_ws_connect(event_data):
print(f"WS接続: {event_data['url']}")
コンテキストマネージャー
# コンテキストマネージャーとして使用し、セッションを自動的に閉じる
async with Client(timeout=30) as client:
resp = await client.get("https://httpbin.org/get")
data = await resp.json()
WebSocketクライアント
client.ws_connect() を使用して WebSocketクライアント接続を確立し、ClientWebSocket オブジェクトを返します。クライアントとサーバーの WebSocket は WebSocketConnectionBase 基底クラスを共有し、send/receive/iter のインターフェースは完全に一致します。
基本的な使い方
from ErisPulse.Core import client
ws = await client.ws_connect("wss://example.com/ws", heartbeat=30)
await ws.send_text("Hello")
await ws.send_bytes(b"\x00\x01\x02")
await ws.send_json({"type": "ping"})
メッセージの受信
高レベルメソッド(推奨)
メッセージの種類を自動的にフィルタリングし、切断時に WebSocketDisconnect をスローします:
from ErisPulse.Core import client
from ErisPulse.Core.Bases.errors import WebSocketDisconnect
ws = await client.ws_connect("wss://example.com/ws")
# 単一のメッセージ受信
text = await ws.receive_text() # str
data = await ws.receive_bytes() # bytes
obj = await ws.receive_json() # dict / list
# 繰り返し受信 (切断時に自動的に停止)
async for text in ws.iter_text():
print(text)
async for data in ws.iter_bytes():
print(data)
async for obj in ws.iter_json():
print(obj)
低レベルメソッド
receive() と iter_messages() を使用して、原始メッセージの種類を処理し、TEXT / BINARY / CLOSE / ERROR を区別できます:
from ErisPulse.Core import client
from ErisPulse.Core.Bases.websocket import WSMessage
ws = await client.ws_connect("wss://example.com/ws")
# 単一の原始メッセージ受信
msg = await ws.receive()
# msg.type -> WSMessage.TEXT / WSMessage.BINARY / WSMessage.CLOSE / WSMessage.ERROR
# msg.data -> str | bytes | None
# 繰り返し原始メッセージ受信 (CLOSE/ERROR で自動的に停止)
async for msg in ws.iter_messages():
if msg.type == WSMessage.TEXT:
print(f"テキスト: {msg.data}")
elif msg.type == WSMessage.BINARY:
print(f"バイナリ: {len(msg.data)} bytes")
WSMessage
WSMessage は、低レベルライブラリに依存しない統一された WebSocketメッセージ型です:
| 属性 | 型 | 説明 |
|---|---|---|
type |
str |
メッセージの種類: WSMessage.TEXT / WSMessage.BINARY / WSMessage.CLOSE / WSMessage.ERROR |
data |
Any |
メッセージデータ |
ClientWebSocket 属性
| 属性 | 型 | 説明 |
|---|---|---|
url |
URL |
接続URL |
headers |
Headers |
レスポンスヘッダー |
closed |
bool |
接続が閉じられているか |
raw |
object |
低レベルの元のオブジェクト (aiohttp.ClientWebSocketResponse) |
ライフサイクルフック
サービス側 WebSocketConnection と同様に、on_disconnect と on_error のコールバックがサポートされています:
from ErisPulse.Core import client
ws = await client.ws_connect("wss://example.com/ws")
@ws.on_disconnect
async def handle_disconnect(ws, reason="unknown"):
print(f"接続が切断されました: {reason}")
@ws.on_error
async def handle_error(ws, error=""):
print(f"接続エラー: {error}")
接続の閉じ方
await ws.close(code=1000, reason="正常な切断")
例外体系
ErisPulse は、統一された例外階層を定義し、sdk.client からリクエストを発行すると、aiohttpの例外がErisPulseの例外に自動的に変換されます。
後方互換性:
aiohttp.ClientSessionを直接使用する古いモジュール/アダプターは完全に影響を受けません。例外変換はsdk.clientからリクエストを発行する場合にのみ有効で、aiohttpを直接使用するコードはaiohttp.ClientErrorなどの元の例外をキャッチします。2つの方法は共存可能です。
例外階層
ErisPulseError
├── ClientError # HTTP/WSクライアントリクエスト例外の基底クラス
│ ├── ClientConnectionError # 接続失敗 (DNS解決失敗、接続拒否、ネットワーク不可)
│ ├── ClientTimeoutError # 接続タイムアウトまたはリクエストタイムアウト
│ └── HTTPStatusError # HTTP 4xx/5xxステータスコードエラー
└── WebSocketError # WebSocket例外の基底クラス
└── WebSocketDisconnect # WebSocket接続切断 (クライアントとサーバー共通)
例外のキャッチ
from ErisPulse.Core import client
from ErisPulse.Core.Bases.errors import (
ClientError,
ClientConnectionError,
ClientTimeoutError,
HTTPStatusError,
WebSocketDisconnect,
WebSocketError,
)
# HTTPリクエストの例外処理
try:
resp = await client.get("https://api.example.com/data")
data = await resp.json()
except ClientConnectionError:
print("サーバーに接続できません")
except ClientTimeoutError:
print("リクエストがタイムアウトしました")
except ClientError as e:
print(f"リクエストが失敗しました: {e}")
# WebSocketの例外処理
try:
ws = await client.ws_connect("wss://example.com/ws")
async for text in ws.iter_text():
await ws.send_text(f"Echo: {text}")
except WebSocketDisconnect as e:
print(f"接続が切断されました: code={e.code}, reason={e.reason}")
except WebSocketError as e:
print(f"WebSocketエラー: {e}")
統一的なキャッチ
ClientError を使用して、HTTP/WSクライアントリクエストのすべての例外を統一的にキャッチします:
from ErisPulse.Core.Bases.errors import ClientError
try:
resp = await client.get("https://api.example.com/data")
except ClientError as e:
print(f"クライアントエラー: {e}")
HTTPStatusError
リクエスト後にステータスコードをチェックして例外をスローする必要がある場合、手動で使用できます:
from ErisPulse.Core.Bases.errors import HTTPStatusError
resp = await client.get("https://api.example.com/data")
if resp.status >= 400:
raise HTTPStatusError(resp.status, await resp.text())
アダプターでの使用
アダプターは、グローバルクライアントまたは独自のクライアントインスタンスを使用してプラットフォームAPIリクエストを送信できます:
from ErisPulse.Core import client
from ErisPulse.Core.Bases import BaseAdapter
from ErisPulse.Core.Bases.errors import ClientError
class MyAdapter(BaseAdapter):
async def call_api(self, endpoint, **params):
try:
resp = await client.post(
f"https://api.platform.com/{endpoint}",
json=params,
headers={"Authorization": f"Bearer {self.token}"},
)
return await resp.json()
except ClientError as e:
self.logger.error(f"API呼び出しに失敗しました: {e}")
raise
from ErisPulse import sdkを使用してsdk.clientを使うことも可能で、効果は同じです。
最適な実践
- グローバルクライアントの優先使用:
from ErisPulse.Core import clientを使用してグローバルシングルトンを取得し、フレームワークによる統一管理と監視を容易にする - 直接 aiohttp のインポートを避ける:
clientを使用してaiohttp.ClientSessionを置き換え、将来の下層実装の変更に伴うコード変更を必要としないようにする。古いコードは直接 aiohttp を使用しても正常に動作し、2つの方法は共存可能 - ErisPulse例外体系の使用:
sdk.clientからのリクエストではaiohttp.ClientErrorではなくClientErrorをキャッチし、特定のHTTPライブラリに依存しないコードを保証する。直接 aiohttp を使用する古いコードは影響を受けない - 適切なタイムアウトの設定:APIの応答速度に応じて適切なタイムアウト時間を設定し、長時間のブロッキングを避ける
- リトライメカニズムの使用:不安定なAPIにはリトライを有効にして、信頼性を高める
- リクエスト統計の監視:
sdk.client.statsまたはclient.requestライフサイクルイベントを使用してリクエスト状況を監視する - WebSocketの高レベルメソッドの使用:
iter_text/iter_jsonなどの高レベルメソッドを優先し、メッセージの種類を区別する必要がある場合にのみiter_messagesを使用する
関連ドキュメント
- ルータマネージャー - HTTP/WebSocketサービス側ルーティング(サービス側WebSocketConnectionとクライアントは同一基底クラスを共有)
- アダプター開発ガイド - アダプターでHTTPクライアントを使用する
- ライフサイクル管理 - リクエストイベントの監視