ErisPulse API アクション標準
Tip
このドキュメントを読むべきタイミング:アダプター内で Api DSL の標準アクション(get_user_info / delete_message など)を実装する場合、またはモジュールからこれらの標準アクションをクロスプラットフォームで呼び出す際に、パラメータや data フィールドを確認したいときに本書を参照してください。必要なければ読み飛ばして構いません。
このドキュメントは、ErisPulse アダプターにおける OneBot12 標準 API アクションの統一インターフェース仕様を定義するものであり、モジュール開発者が標準インターフェースに向けてプログラミングできるようにし、プラットフォームネイティブ API へのマッピングはアダプターが担当します。
対象範囲:OneBot12 標準アクションのうち、
ApiDSLはユーザー / グループ / ギルド(Guild)/ メッセージ管理 / メタ(Meta)の通常インターフェースに対する強く型付けされたメソッドを提供します (send_messageはSendDSL.Raw_ob12が担当)。ファイルリソースアクション (upload_file/get_file/ 分割転送)はフォールバックのパススルーとしてのみ保持されており、 §3.5 の説明を参照してください。プラットフォーム拡張アクションはApi.call("prefix.action", ...)というエスケープハッチで呼び出します。アクションのパラメータと戻り値の構造は OneBot12 仕様(リポジトリ内onebot/specs/interface/)を正とします。
1. 設計の背景
ErisPulse では、メッセージセグメント(メッセージの送受信)とイベント形式はすでに OneBot12 標準に完全に準拠していますが、API アクション呼び出し(ユーザー情報の取得、グループ一覧の取得、メッセージの取り消しなど)はこれまで統一されておらず——モジュール開発者はプラットフォームごとに異なる call_api 呼び出しを書く必要がありました。
ApiDSL は強く型付けされた標準アクションメソッドを提供することで、この問題を解決します:
モジュールコード(クロスプラットフォーム統一) アダプター実装(プラットフォーム固有)
───────────────── ──────────────────
adapter.Api.get_user_info("123") → アダプターの call_api / オーバーライド
adapter.Api.get_group_list() → アダプターの call_api / オーバーライド
adapter.Api.delete_message("id") → アダプターの call_api / オーバーライド
2. 3 層 DSL の並列構造
ErisPulse のアダプターには、それぞれが役割を担う 3 つの並列した DSL 内部クラスが存在します:
BaseAdapter
├── Send(SendDSL) ← メッセージ送信(Text/Image/Raw_ob12)
├── Request(RequestDSL) ← リクエスト操作(accept/reject)
└── Api(ApiDSL) ← 標準 API アクション(ユーザー/グループ/ギルド/メッセージ管理/ファイル/メタ)★
| DSL | 役割 | メソッドスタイル | 戻り値 |
|---|---|---|---|
Send |
メッセージ送信 | メソッドチェーン + asyncio.Task |
標準レスポンス |
Request |
リクエストイベントの処理 | asyncio.Task |
標準レスポンス |
Api |
クエリ/管理操作 | async メソッド |
標準レスポンス |
3. 標準アクション一覧
3.1 ユーザー関連
| メソッド | OB12 アクション | パラメータ | data 戻り値 |
|---|---|---|---|
get_self_info() |
get_self_info |
なし | user_id, user_name, user_displayname |
get_user_info(user_id) |
get_user_info |
user_id: str |
user_id, user_name, user_displayname, user_remark |
get_friend_list() |
get_friend_list |
なし | list[get_user_info レスポンス] |
3.2 グループ関連
| メソッド | OB12 アクション | パラメータ | data 戻り値 |
|---|---|---|---|
get_group_info(group_id) |
get_group_info |
group_id: str |
group_id, group_name |
get_group_list() |
get_group_list |
なし | list[get_group_info レスポンス] |
get_group_member_info(group_id, user_id) |
get_group_member_info |
group_id: str, user_id: str |
user_id, user_name, user_displayname |
get_group_member_list(group_id) |
get_group_member_list |
group_id: str |
list[get_group_member_info レスポンス] |
set_group_name(group_id, group_name) |
set_group_name |
group_id: str, group_name: str |
なし |
leave_group(group_id) |
leave_group |
group_id: str |
なし |
3.3 メッセージ管理
| メソッド | OB12 アクション | パラメータ | 説明 |
|---|---|---|---|
delete_message(message_id) |
delete_message |
message_id: str |
メッセージの取り消し/削除 |
メッセージ送信(
send_message)はSendDSLのRaw_ob12が担当するため、ApiDSLでは重複提供しません。
3.4 ギルド(Guild)関連
OneBot12 のギルド体系は 2 階層に分かれます:ギルド(guild) と サブチャンネル(channel)。
| メソッド | OB12 アクション | パラメータ | data 戻り値 |
|---|---|---|---|
get_guild_info(guild_id) |
get_guild_info |
guild_id: str |
guild_id, guild_name |
get_guild_list() |
get_guild_list |
なし | list[get_guild_info レスポンス] |
set_guild_name(guild_id, guild_name) |
set_guild_name |
guild_id: str, guild_name: str |
なし |
get_guild_member_info(guild_id, user_id) |
get_guild_member_info |
guild_id: str, user_id: str |
user_id, user_name, user_displayname |
get_guild_member_list(guild_id) |
get_guild_member_list |
guild_id: str |
list[get_guild_member_info レスポンス] |
leave_guild(guild_id) |
leave_guild |
guild_id: str |
なし |
get_channel_info(guild_id, channel_id) |
get_channel_info |
guild_id: str, channel_id: str |
channel_id, channel_name |
get_channel_list(guild_id, *, joined_only) |
get_channel_list |
guild_id: str, joined_only: bool=false |
list[get_channel_info レスポンス] |
set_channel_name(guild_id, channel_id, channel_name) |
set_channel_name |
guild_id, channel_id, channel_name |
なし |
get_channel_member_info(guild_id, channel_id, user_id) |
get_channel_member_info |
guild_id, channel_id, user_id |
user_id, user_name, user_displayname |
get_channel_member_list(guild_id, channel_id) |
get_channel_member_list |
guild_id, channel_id |
list[get_channel_member_info レスポンス] |
leave_channel(guild_id, channel_id) |
leave_channel |
guild_id, channel_id |
なし |
ギルド体系とグループ(group)は互いに独立しています:Discord / QQ ギルド / Kook などのプラットフォームはギルドインターフェースを実装し、 従来の QQ / WeChat はグループインターフェースを実装します。両方が同時に存在する場合もあれば、どちらか一方のみの場合もあります。
3.5 ファイルリソース操作
Warning
ファイルリソースモデル(file_id 2 段階方式)は ErisPulse では「フォールバックで利用可能」に位置づけられます:
ErisPulse のファイル送受信は「先にアップロードして file_id を取得し、それを参照する」モデルを採用していません——モジュールがファイルを送信するには
SendDSL.File(file, filename) を使用します(URL / パス / バイトは送信時に直接転送、
送信メソッド仕様 を参照)。
本節の upload_file / get_file / 分割転送アクションはプラットフォーム固有の file_id ファイルリソース
機能に依存しており、汎用性が不十分です。アダプターのバックエンドが当該機能を本来備えている場合にのみパススルーが可能で、フレームワーク内蔵の
アダプターは実装せず、実装も推奨しません。呼び出すと通常 retcode=10002 が返されます。
モジュールがクロスプラットフォームでファイルを送信する必要がある場合は SendDSL.File を使用し、file_id に依存しないでください。
展望:file_id リソースモデルのフレームワーク層への標準化は今後の方向性ですが、現在のバージョンでは提供されていません。
一括転送(小さいファイル):
| メソッド | OB12 アクション | パラメータ | data 戻り値 |
|---|---|---|---|
upload_file(*, type, name, ...) |
upload_file |
type, name, url/path/data, headers?, sha256? |
file_id |
get_file(file_id, type) |
get_file |
file_id: str, type: str |
name, url/path/data |
upload_file の type パラメータ:
"url":URL 経由でアップロード(urlの指定が必要)"path":ローカルパス経由でアップロード(pathの指定が必要)"data":バイナリデータ経由でアップロード(dataの指定が必要)
3.5.1 分割転送(大きなファイル、上記のフォールバック対象)
OneBot12 の分割アクションは stage で段階を区別します。ApiDSL は同一アクションの 3 段階/2 段階を独立したメソッドに分割します
(offset はバイトオフセット、data は JSON 内では Base64)。以下の表は参照用にのみ残しており、
アダプターは実装する必要がなく、強制的に実装すべきでもありません:
分割アップロードの 3 ステップ:prepare → transfer(断片ごとにループ)→ finish
| メソッド | 対応 stage | パラメータ | data 戻り値 |
|---|---|---|---|
upload_file_fragmented_prepare(name, total_size) |
prepare |
name: str, total_size: int |
file_id(転送中に使用) |
upload_file_fragmented_transfer(file_id, offset, data) |
transfer |
file_id, offset: int, data: bytes |
なし |
upload_file_fragmented_finish(file_id, sha256) |
finish |
file_id, sha256: str(ファイル全体の検証) |
file_id |
total = os.path.getsize(path)
r = await adapter.Api.upload_file_fragmented_prepare(os.path.basename(path), total)
fid = r["data"]["file_id"]
offset = 0
with open(path, "rb") as f:
while chunk := f.read(65536):
await adapter.Api.upload_file_fragmented_transfer(fid, offset, chunk)
offset += len(chunk)
sha256 = hashlib.sha256(open(path, "rb").read()).hexdigest()
await adapter.Api.upload_file_fragmented_finish(fid, sha256)
分割ダウンロードの 2 ステップ:prepare → transfer(断片を取得するループ)
| メソッド | 対応 stage | パラメータ | data 戻り値 |
|---|---|---|---|
get_file_fragmented_prepare(file_id) |
prepare |
file_id |
name, total_size, sha256 |
get_file_fragmented_transfer(file_id, offset, size) |
transfer |
file_id, offset: int, size: int |
data(今回の分割断片のバイト列) |
3.6 メタ(Meta)アクション
メタアクションは特定のアカウントを対象としないため、Using() で Bot を指定する必要はありません。
| メソッド | OB12 アクション | パラメータ | data 戻り値 |
|---|---|---|---|
get_latest_events(limit, timeout) |
get_latest_events |
limit: int=0, timeout: int=0 |
イベントオブジェクトの配列(メタイベントを除く) |
get_supported_actions() |
get_supported_actions |
なし | list[str] サポート対象のアクション名 |
get_status() |
get_status |
なし | good: bool, bots: list[{self, online, ...}] |
get_version() |
get_version |
なし | impl, version, onebot_version |
3.7 汎用拡張アクション
| メソッド | 説明 |
|---|---|
call(action, **params) |
プラットフォーム拡張アクションのエスケープハッチ。OB12 拡張命名規則 {prefix}.{action} に従う |
4. 使用方法
4.1 基本的な呼び出し
from ErisPulse import adapter
# ユーザー情報を取得(クロスプラットフォーム統一)
result = await adapter.myplatform.Api.get_user_info("123456")
if result["status"] == "ok":
user_name = result["data"]["user_name"]
print(f"ユーザー名: {user_name}")
# グループ一覧を取得
result = await adapter.myplatform.Api.get_group_list()
groups = result["data"]
# メッセージを取り消し
await adapter.myplatform.Api.delete_message("msg_123456")
4.2 Bot アカウントの指定(マルチアカウントモード)
# 指定した Bot アカウントで操作を実行
info = await adapter.myplatform.Api.Using("bot1").get_self_info()
4.3 プラットフォーム拡張アクション
# プラットフォーム固有の拡張アクションを呼び出す({prefix}.{action} の命名を推奨)
result = await adapter.telegram.Api.call(
"telegram.send_sticker",
sticker_id="CAACAgIAAxkBAA...",
)
4.4 イベントハンドラーでの使用
from ErisPulse.Core.Event import message
@message()
async def handle(event):
# 送信者の詳細情報を取得
user_id = event.get_user_id()
platform = event.get_platform()
result = await getattr(adapter, platform).Api.get_user_info(user_id)
if result["status"] == "ok":
user_name = result["data"]["user_name"]
await event.reply(f"こんにちは、{user_name}さん!")
5. アダプター実装
5.1 デフォルト動作(ゼロコンフィグ)
ApiDSL のデフォルト実装は、標準アクション名を endpoint としてそのまま adapter.call_api() に渡します:
# ApiDSL のデフォルト実装と等価:
async def get_user_info(self, user_id: str) -> dict:
return await self._adapter.call_api("get_user_info", user_id=user_id, account_id=self._account_id)
アカウントフィールド:フレームワークはアダプターの
call_apiにおける実際の消費方法に応じてアカウントバインディングを自動で適合させます(標準名はaccount_id;旧名_account_idは自動書き換え;関数本体内のparams.popも同様に認識)。消費されない場合は、プラットフォームパラメータへの漏出を避けるためこのフィールドを除去し、一度だけヒントを表示します——消費形態の詳細は アダプター開発 - アカウント解決 を参照してください。
適用シナリオ:アダプターの基盤となるバックエンド自体が OneBot12 標準アクションプロトコルに準拠している場合、
call_api は標準アクション名をそのままサポートします(当該プロトコルに準拠するサーバーに直接接続する場合など)。
5.2 標準メソッドのオーバーライド(プラットフォームネイティブ API へのマッピング)
アダプターは個々の標準メソッドをオーバーライドし、プラットフォームネイティブ API にマッピングできます:
class MyAdapter(BaseAdapter):
class Api(BaseAdapter.Api):
"""MyPlatform 標準 API アクションの実装"""
async def get_user_info(self, user_id: str) -> dict:
# プラットフォームネイティブ API へのマッピング
raw = await self._adapter._request("GET", f"/users/{user_id}")
if raw.get("code") != 0:
# プラットフォーム側エラー:341xx~345xx 段の下 3 桁をカスタム使用(346xx はフレームワーク予約のため使用しないこと)
return self._adapter.make_error(retcode=34400, message="ユーザーが存在しません")
user = raw["data"]
return self._adapter.make_response(
data={
"user_id": str(user["id"]),
"user_name": user.get("nick", ""),
"user_displayname": user.get("display_name", ""),
"user_remark": user.get("remark", ""),
},
raw=raw,
)
async def get_friend_list(self) -> dict:
raw = await self._adapter._request("GET", "/friends")
friends = [
{
"user_id": str(u["id"]),
"user_name": u.get("nick", ""),
"user_displayname": u.get("display_name", ""),
"user_remark": u.get("remark", ""),
}
for u in raw.get("data", [])
]
return self._adapter.make_response(data=friends, raw=raw)
5.3 サポートされていないアクション
アダプターがオーバーライドしていない標準メソッドはデフォルト実装(call_api への委譲)に従います。call_api もそのアクションをサポートしていない場合は、標準エラーレスポンスを返す必要があります:
async def call_api(self, endpoint: str, **params):
if endpoint not in self._supported_endpoints:
return self.make_error(retcode=10002, message=f"サポートされていないアクション: {endpoint}")
# ... プラットフォーム API の呼び出し
モジュール開発者は戻り値の retcode でサポートされているかどうかを判断できます:
result = await adapter.myplatform.Api.get_friend_list()
if result["retcode"] == 10002:
print("このプラットフォームはフレンドリストの取得をサポートしていません")
6. レスポンス形式
すべての ApiDSL メソッドは標準 API レスポンス形式を返します(詳細は API レスポンス標準 を参照):
{
"status": "ok",
"retcode": 0,
"data": { ... },
"message_id": "",
"message": "",
"myplatform_raw": { ... }
}
注意:情報照会系アクションの
message_idは空文字列です(message_idが設定されるのはメッセージ送信系アクションのみです)。
7. SendDSL / RequestDSL との関係
| シナリオ | 使用する DSL | 例 |
|---|---|---|
| メッセージ送信 | Send |
adapter.Send.To("group", "123").Text("hi") |
| リクエストの承認/拒否 | Request |
adapter.Request("req_id").accept() |
| ユーザー/グループ情報の取得 | Api |
adapter.Api.get_user_info("123") |
| メッセージの取り消し | Api |
adapter.Api.delete_message("msg_id") |
| グループからの退出 | Api |
adapter.Api.leave_group("group_id") |
8. アダプター実装チェックリスト
標準アクション
-
call_apiが標準アクション名を処理できる(または対応するApiDSLメソッドをオーバーライドする) - サポートされていないアクションは
retcode=10002を返す - 戻り値は標準 API レスポンス形式に従う
-
dataフィールドに OB12 標準で定義されたフィールドが含まれている - ギルドプラットフォームは
get_guild_*/get_channel_*/leave_guild/leave_channelを実装する必要がある - メタアクション(
get_status/get_version/get_supported_actions)の実装を推奨 - ファイル送受信は
SendDSL.File(直接転送)を使用;ファイルリソースアクション(upload_file/get_file/分割転送)の実装は強制ではない。バックエンドがfile_idリソース機能を備えている場合にのみパススルーが必要
拡張アクション
- プラットフォーム拡張アクションは
{prefix}.{action}の命名を使用する - 拡張アクションのパラメータとレスポンスも OB12 のアクション要求/レスポンス構造に従う
9. 関連ドキュメント
Api DSL の戻り値実装時の対照資料:
- API レスポンス標準 - アダプター API レスポンス形式の標準
同一アダプターのその他の DSL:
イベント側の関連資料:
- イベント変換標準 - イベント形式とメッセージセグメントの標準