アダプターシステム API
Tip
このドキュメントを読むべきケース:アダプターの管理(インスタンスの取得、起動・停止、Bot のオンライン状態の確認)、Send DSL によるメッセージ送信、ミドルウェアの登録、またはアダプターへの Bot ステータス報告(meta イベント)の実装が必要な場合に本文をご参照ください。該当しない場合はスキップしてください。
このドキュメントでは、ErisPulse アダプターシステムの API について詳しく説明します。
Adapter マネージャー
アダプターの取得
from ErisPulse import sdk
# 名前でアダプターを取得
adapter = sdk.adapter.get("platform_name")
# または、属性で直接アクセスすることもできます
adapter = sdk.adapter.platform_name
アダプターイベントリスナーの使用
通常は、イベントの監視/処理には
Eventモジュールを使用することをお勧めします。また、
Eventモジュールは強力なラッパーを提供しており、モジュール開発にさらに便利さをもたらします。
# OneBot12 標準イベントをリッスン
@sdk.adapter.on("message")
async def handle_message(event):
pass
# 特定プラットフォームの標準イベントをリッスン
@sdk.adapter.on("message", platform="yunhu")
async def handle_yunhu_message(event):
pass
# プラットフォームのネイティブイベントをリッスン
@sdk.adapter.on("raw_event", raw=True, platform="yunhu")
async def handle_raw_event(data):
pass
アダプターの管理
# すべてのプラットフォームを取得
platforms = sdk.adapter.platforms
# アダプターが存在するかどうかを確認
exists = sdk.adapter.exists("platform_name")
# アダプターの有効化/無効化
sdk.adapter.enable("platform_name")
sdk.adapter.disable("platform_name")
# アダプターの起動/終了
# 以下のメソッドはいずれも引数を渡す場合の例であり、引数なしの場合は登録済みのすべてのアダプターの起動/停止を意味します
await sdk.adapter.startup(["platform1", "platform2"])
await sdk.adapter.shutdown(["platform1", "platform2"])
# アダプターが実行中かどうかを確認
is_running = sdk.adapter.is_running("platform_name")
# 実行中のすべてのアダプターを一覧表示
running = sdk.adapter.list_running()
# アダプターのメタ情報を取得(module.get_meta と整合、パネル/ストアなどで利用される)
info = sdk.adapter.get_info("platform_name") # 登録情報(meta + クラス名、json-safe)
meta = sdk.adapter.get_meta("platform_name") # 紹介メタ情報(description は i18n 解析に対応)
raw = sdk.adapter.get_meta("platform_name", resolve_i18n=False) # 生の i18n 辞書をそのまま返す
ミドルウェア
ミドルウェアは、イベントがハンドラーにディスパッチされる前に実行され、イベントデータの変更、フィルタリング、記録などを行うことができます。
ミドルウェアの登録
@sdk.adapter.middleware
async def my_middleware(event):
sdk.logger.info(f"ミドルウェア処理: {event}")
return event
ミドルウェアの実行モデル
- 実行順序:ミドルウェアは登録順に実行されます(先に登録されたものが先に実行される)
- データの受け渡し:各ミドルウェアは、直前のミドルウェアが返した
eventデータを受け取ります。いずれかのミドルウェアがNoneを返した場合、その戻り値は無視され、元のデータが保持されたまま引き続き渡されます(同時にwarningレベルのログが出力されます) - データの変更:ミドルウェアはイベントデータを変更し、変更後の辞書を返すことができます
- イベントの否決:ミドルウェアが明示的に
Falseを返した場合、イベントは否決されます。イベントは破棄され、どのハンドラーにも渡されず、アウトバウンドの副作用も一切発生しません。否決時には TRACE ログが出力され、adapter.event.blockedライフサイクルフックがトリガーされます(ミドルウェア名と完全なイベントが渡されます)
@sdk.adapter.middleware
async def add_timestamp(event):
event["processed_at"] = time.time()
return event
@sdk.adapter.middleware
async def filter_spam(event):
if event.get("detail_type") == "private":
text = event.get("alt_message", "")
if "スパム広告" in text:
return False # 否決:イベントは破棄され、どのハンドラーにも渡されません
return event
注意:イベントを否決するのは、明示的に
Falseを返した場合のみです(空の辞書 /0/""などの falsy 値を返しても否決されません)。Noneを返した場合も通過し、ペイロードは変更されません。否決されたイベントは、adapter.event.blockedフックをリッスンすることで、「イベントがなぜ応答しなかったのか」の監査や調査が可能です。
Send メッセージ送信
基本的な送信
# アダプターを取得
adapter = sdk.adapter.get("platform")
# テキストメッセージを送信
await adapter.Send.To("user", "123").Text("Hello")
# 画像メッセージを送信
await adapter.Send.To("group", "456").Image("https://example.com/image.jpg")
送信アカウントの指定
# アカウント名を使用
await adapter.Send.Using("account1").To("user", "123").Text("Hello")
# アカウント ID を使用
await adapter.Send.Using("bot_id").To("user", "123").Text("Hello")
サポートされる送信メソッドの照会
# プラットフォームがサポートするすべての送信メソッドを一覧表示
methods = sdk.adapter.list_sends("onebot11")
# 戻り値: ["Text", "Image", "Voice", "Markdown", ...]
# 特定のメソッドの詳細情報を取得
info = sdk.adapter.send_info("onebot11", "Text")
# 戻り値:
# {
# "name": "Text",
# "parameters": [
# {"name": "text", "type": "str", "default": null, "annotation": "str"}
# ],
# "return_type": "Awaitable[Any]",
# "docstring": "テキストメッセージを送信..."
# }
チェーン装飾
# @ユーザー
await adapter.Send.To("group", "456").At("789").Text("こんにちは")
# @全員
await adapter.Send.To("group", "456").AtAll().Text("皆さん、こんにちは")
# メッセージに返信
await adapter.Send.To("group", "456").Reply("msg_id").Text("返信内容")
# 組み合わせて使用
await adapter.Send.To("group", "456").At("789").Reply("msg_id").Text("@したメッセージへの返信")
API 呼び出し
call_api メソッド
注意:
call_apiはプラットフォームのネイティブ API を直接呼び出す低レベルメソッドです。パラメータや戻り値はプラットフォームによって異なる場合があるため、対応するプラットフォームのアダプタードキュメントをご参照ください。メッセージの送信には Send DSL の使用をお勧めします。call_apiは、Send DSL が対応していないシナリオ(プラットフォーム固有のデータの取得やプラットフォーム管理インターフェースの呼び出しなど)でのみ使用してください。
# プラットフォーム API を呼び出す
result = await adapter.call_api(
endpoint="/send",
content="Hello",
recvId="123",
recvType="user"
)
# 標準化されたレスポンス
{
"status": "ok",
"retcode": 0,
"data": {...},
"message_id": "msg_id",
"message": "",
"{platform}_raw": raw_response
}
アダプター基底クラス
BaseAdapter のメソッド
from ErisPulse import sdk
from ErisPulse.Core import BaseAdapter
class MyAdapter(BaseAdapter):
def __init__(self):
super().__init__()
self.sdk = sdk
# アダプターの初期化
pass
async def start(self):
"""アダプターを起動する(実装必須)"""
pass
async def shutdown(self):
"""アダプターを終了する(実装必須)"""
pass
async def call_api(self, endpoint: str, **params):
"""プラットフォーム API を呼び出す(実装必須)"""
pass
Send ネストクラス
class MyAdapter(BaseAdapter):
class Send(BaseAdapter.Send):
def Text(self, text: str):
"""テキストメッセージを送信する"""
import asyncio
return asyncio.create_task(
self._adapter.call_api(
endpoint="/send",
content=text,
recvId=self._target_id,
recvType=self._target_type
)
)
Bot ステータス管理
アダプターは、OneBot12 標準の meta イベントを送信することで、フレームワークに Bot の接続状態を通知します。システムはそこから自動的に Bot 情報を抽出し、ステータスの追跡を行います。
meta イベントの報告
アダプターは meta イベントを通じて Bot のステータスを報告します。detail_type は 3 種類あります:connect(登録してオンライン)、heartbeat(ハートビートによる生存維持)、disconnect(オフラインとしてマーク)。emit_meta() を使って 1 行で送信することをお勧めします。meta イベントを送信しない場合でも、フレームワークは通常のイベント(message/notice/request)の self フィールドから自動的に Bot を検出します。
- meta イベントの形式と送信方法(送信タイミング、
emit_meta()の使い方、手動での形式構築)については、アダプターのベストプラクティス - Bot ステータス管理と Meta イベント をご参照ください - 自動検出メカニズムとフレームワークの動作については、アダプターのコアコンセプト - Bot ステータス管理 をご参照ください
Bot ステータスの照会
# すべてのアダプターと Bot の完全なステータスを取得(WebUI フレンドリー)
summary = sdk.adapter.get_status_summary()
# {
# "adapters": {
# "telegram": {
# "status": "started",
# "bots": {
# "123456": {
# "status": "online",
# "last_active": 1712345678.0,
# "info": {"nickname": "MyBot"}
# }
# }
# }
# }
# }
# すべての Bot を一覧表示
all_bots = sdk.adapter.list_bots()
# 指定したプラットフォームの Bot を一覧表示
tg_bots = sdk.adapter.list_bots("telegram")
# 単一の Bot の詳細を取得
info = sdk.adapter.get_bot_info("telegram", "123456")
# Bot がオンラインかどうかを確認
if sdk.adapter.is_bot_online("telegram", "123456"):
print("Bot はオンラインです")
Bot ステータスの値
| ステータス | 説明 |
|---|---|
online |
オンライン(イベントを継続的に受信、またはアダプターによる明示的なマーク) |
offline |
オフライン(アダプターによる明示的なマーク、またはシステム終了時に自動設定) |
unknown |
不明(登録のみでステータス未確認) |
ライフサイクルイベント
| イベント名 | 発生タイミング | データ |
|---|---|---|
adapter.bot.online |
新しい Bot を初めて自動検出した時 | {platform, bot_id, status} |
adapter.status.change |
アダプターのステータス変化時 | {platform, status}。status のすべての値:starting / started / start_failed / stopping / stopped / stop_failed / skipped-dependency(依存するアダプターが未準備のため起動をスキップ)/ disabled(設定により無効化) |
# Bot オンラインイベントをリッスン
@sdk.lifecycle.on("adapter.bot.online")
def on_bot_online(event):
print(f"Bot がオンライン: {event['data']['platform']}/{event['data']['bot_id']}")
# アダプターのステータス変化をリッスン
@sdk.lifecycle.on("adapter.status.change")
def on_status_change(event):
print(f"アダプター状態: {event['data']['platform']} -> {event['data']['status']}")
システム終了時(
shutdown)には、すべての Bot が自動的にofflineとしてマークされます。
関連ドキュメント
API の参照を続ける:
- コアモジュール API - コアモジュールの API
- イベントシステム API - Event モジュールの API
アダプターを書いてみる:
- アダプター開発ガイド - プラットフォームアダプターの開発
- アダプター標準化ガイド(総綱) - 新しいアダプターを実装する前の標準照合と Checklist