イベントコンバーター実装ガイド
Tip
この文書を読むべきタイミング:アダプター開発パス内では必読(イベントコンバーター)。必要なければスキップしても、他の機能の利用には影響しません。
アダプターがプラットフォームのネイティブイベントを受信すると、イベントコンバーター (Converter) がそれを ErisPulse の統一された OneBot12 標準形式へ変換します。プラットフォームイベントがどのようにフレームワークへ取り込まれるかは、この1つのクラスが決定します。
Converter の責務
プラットフォームネイティブイベント ──→ Converter.convert() ──→ OneBot12 標準イベント
Converter は順方向変換(受信方向)のみを担当します。つまり、プラットフォームのネイティブイベントデータを OneBot12 標準形式に変換します。逆方向変換(送信方向)は Send.Raw_ob12() メソッドが処理します。
基本原則
- 無損失変換:元のデータは必ず
{platform}_rawフィールドに完全な形で保持すること - 標準互換:変換後のイベントは OneBot12 標準形式に準拠すること
- プラットフォーム拡張:プラットフォーム固有のデータは
{platform}_プレフィックス付きフィールドに保存すること
BaseConverter 基底クラス(推奨)
2.7.0 以降、フレームワークは BaseConverter 基底クラス(ErisPulse.Core.Bases)を提供しており、OneBot12 イベントの共通フィールド構築とよく使うメッセージセグメントのヘルパーをカプセル化しているため、コンバーターは型マッピングに集中するだけでよくなります:
from ErisPulse.Core.Bases import BaseConverter
class MyConverter(BaseConverter):
def __init__(self):
super().__init__(platform="myplatform")
def convert(self, raw_event: dict) -> dict | None:
if not isinstance(raw_event, dict):
return None
event_type = raw_event.get("type", "")
base = self.build_base_event(raw_event, event_type) # id/time/platform/self/raw
if event_type == "message":
base["type"] = "message"
base["detail_type"] = "group" if raw_event.get("group_id") else "private"
base["user_id"] = str(raw_event.get("sender_id", ""))
base["message"] = [self.text(raw_event.get("content", ""))]
base["alt_message"] = raw_event.get("content", "")
return base
return None
build_base_event() が自動的に埋める共通フィールド:
| フィールド | 供給元 |
|---|---|
id |
raw_event["event_id"]、未指定時は UUID を自動生成 |
time |
raw_event["timestamp"]、未指定時は現在時刻 |
platform |
コンストラクタで渡された platform |
self |
{"platform": ..., "user_id": raw_event["bot_id"]} |
{platform}_raw |
元のイベント(「無損失変換」の原則を満たす) |
{platform}_raw_type |
元のイベントタイプ |
よく使うメッセージセグメントのヘルパーメソッド(いずれも静的メソッドで、そのまま再利用できます):
converter.text("hi") # {"type": "text", "data": {"text": "hi"}}
converter.at("123456") # {"type": "at", "data": {"user_id": "123456"}}
converter.image("file.png") # {"type": "image", "data": {"file": "file.png"}}
手動で実装する場合、
build_base_eventの共通フィールド構築は毎回書く必要があるボイラープレートコードです。BaseConverterを使えばこの部分を省略でき、「無損失変換」(元のイベントは常に{platform}_rawに入る)も自然に満たされます。
convert() メソッド
メソッドシグネチャ
def convert(self, raw_event: dict) -> dict:
"""
プラットフォームのネイティブイベントを OneBot12 標準形式に変換する
:param raw_event: プラットフォームのネイティブイベントデータ
:return: OneBot12 標準形式のイベント辞書
"""
pass
戻り値の構造
変換後のイベント辞書には、以下の標準フィールドを含める必要があります:
{
"id": "イベントの一意なID",
"time": 1234567890, # Unix タイムスタンプ(秒)
"type": "message", # イベントタイプ
"detail_type": "private", # 詳細タイプ
"platform": "myplatform", # プラットフォーム名
"self": {
"platform": "myplatform",
"user_id": "bot_user_id"
},
# メッセージイベントのフィールド
"user_id": "sender_id",
"message": [...], # OneBot12 メッセージセグメントのリスト
"alt_message": "プレーンテキストの内容",
# 元のデータを必ず保持する
"myplatform_raw": { ... }, # プラットフォームネイティブイベントの完全なデータ
"myplatform_raw_type": "ネイティブイベントの型名",
}
必須フィールドのマッピング
共通フィールド(すべてのイベントタイプ)
| OB12 フィールド | 型 | 説明 |
|---|---|---|
id |
str | イベントの一意な識別子 |
time |
int | Unix タイムスタンプ(秒) |
type |
str | イベントタイプ:message / notice / request / meta |
detail_type |
str | 詳細タイプ:private / group / friend など |
platform |
str | プラットフォーム名。アダプターの登録名と一致させること |
self |
dict | ボット情報:{"platform": "...", "user_id": "..."} |
メッセージイベントの追加フィールド
| OB12 フィールド | 型 | 説明 |
|---|---|---|
user_id |
str | 送信者 ID |
message |
list[dict] | OneBot12 メッセージセグメントのリスト |
alt_message |
str | プレーンテキストの代替内容 |
通知イベントの追加フィールド
| OB12 フィールド | 型 | 説明 |
|---|---|---|
user_id |
str | 関連するユーザー ID |
operator_id |
str | 操作者の ID(グループメンバーの増減など) |
メッセージセグメントの変換
OneBot12 標準では、以下のメッセージセグメントタイプが定義されています:
# テキスト
{"type": "text", "data": {"text": "Hello"}}
# 画像
{"type": "image", "data": {"file": "https://example.com/img.jpg"}}
# 音声
{"type": "audio", "data": {"file": "https://example.com/audio.mp3"}}
# 動画
{"type": "video", "data": {"file": "https://example.com/video.mp4"}}
# ファイル
{"type": "file", "data": {"file": "https://example.com/doc.pdf"}}
# @メンション
{"type": "mention", "data": {"user_id": "123"}}
# @全員
{"type": "mention_all", "data": {}}
# 返信
{"type": "reply", "data": {"message_id": "msg_123"}}
プラットフォームに対応していないメッセージセグメントタイプがある場合は、そのセグメントを省略するか、最も近い標準タイプに変換できます。
alt_message のレンダリング規約
alt_message はメッセージイベントのプレーンテキストの代替内容で、ログのアーカイブ、extract_text によるテキストマッチング、コマンドディスパッチのフォールバックに使用されます。各アダプターは alt_message を生成する際、以下の規約に従う必要があります(特に mention セグメントに注意):
- mention セグメントは優先的に
@ニックネームとレンダリングします。プラットフォームがニックネームを提供しない場合は@{user_id}にフォールバックし、user_idがall(@全員)の場合は@メンバー全員とレンダリングします - ニックネームと
user_idの両方が欠けている場合はそのセグメントを省略し、空の"@"を出力してはいけません。"@ ヘルプ"のようになると、テキストマッチングやコマンド解析の基準が汚染されます data.get("user_name", fallback)の罠に注意:メッセージセグメントの構築時にuser_nameのデフォルトとして空文字列が保存されていると、キーが存在するためにフォールバックが永久に機能しません。data.get("user_name") or data.get("user_id")という書き方を使うべきです- その他のメッセージセグメントのレンダリングスタイル(
[画像]、[音声]など)や、セグメント間の連結方法(""または" ")は、アダプター自身の既存の方針を維持し、強制的な統一は行いません
# mention セグメントのレンダリング例
data = seg.get("data") or {}
user_id = str(data.get("user_id") or "").strip()
user_name = str(data.get("user_name") or "").strip()
if user_id == "all":
parts.append("@メンバー全員")
elif user_name:
parts.append(f"@{user_name}")
elif user_id:
parts.append(f"@{user_id}")
プラットフォーム拡張フィールド
プラットフォーム固有のデータは、標準フィールドとの衝突を避けるため {platform}_ プレフィックスを付けて保存する必要があります:
{
# 標準フィールド
"type": "message",
"detail_type": "group",
# ...
# プラットフォーム拡張フィールド
"myplatform_raw": { ... }, # 元のイベントデータ(必須)
"myplatform_raw_type": "chat", # 元のイベントタイプ(必須)
# その他のプラットフォーム固有フィールド
"myplatform_group_name": "グループ名",
"myplatform_sender_role": "admin",
}
重要:
{platform}_rawフィールドは必須です。ErisPulse のイベントシステムやモジュールは、プラットフォームの元のデータにアクセスするためにこのフィールドに依存している可能性があります。
完全な実装例
以下は完全な Converter の実装例です:
class MyConverter:
def __init__(self, platform: str):
self.platform = platform
def convert(self, raw_event: dict) -> dict:
event_type = raw_event.get("type", "")
base_event = {
"id": raw_event.get("id", ""),
"time": raw_event.get("timestamp", 0),
"platform": self.platform,
"self": {
"platform": self.platform,
"user_id": raw_event.get("self_id", ""),
},
"myplatform_raw": raw_event,
"myplatform_raw_type": event_type,
}
if event_type == "chat":
return self._convert_message(raw_event, base_event)
elif event_type == "notification":
return self._convert_notice(raw_event, base_event)
elif event_type == "request":
return self._convert_request(raw_event, base_event)
return base_event
def _convert_message(self, raw: dict, base: dict) -> dict:
base["type"] = "message"
base["detail_type"] = "group" if raw.get("group_id") else "private"
base["user_id"] = raw.get("sender_id", "")
base["message"] = self._convert_message_segments(raw.get("content", ""))
base["alt_message"] = raw.get("content", "")
if raw.get("group_id"):
base["group_id"] = raw["group_id"]
return base
def _convert_message_segments(self, content: str) -> list:
segments = []
if content:
segments.append({"type": "text", "data": {"text": content}})
return segments
def _convert_notice(self, raw: dict, base: dict) -> dict:
base["type"] = "notice"
notification_type = raw.get("notification_type", "")
if notification_type == "member_join":
base["detail_type"] = "group_member_increase"
base["user_id"] = raw.get("user_id", "")
base["group_id"] = raw.get("group_id", "")
base["operator_id"] = raw.get("operator_id", "")
elif notification_type == "friend_add":
base["detail_type"] = "friend_increase"
base["user_id"] = raw.get("user_id", "")
return base
def _convert_request(self, raw: dict, base: dict) -> dict:
base["type"] = "request"
request_type = raw.get("request_type", "")
if request_type == "friend":
base["detail_type"] = "friend"
base["user_id"] = raw.get("user_id", "")
base["comment"] = raw.get("message", "")
elif request_type == "group_invite":
base["detail_type"] = "group"
base["group_id"] = raw.get("group_id", "")
base["user_id"] = raw.get("inviter_id", "")
return base
リッチメディアメッセージの変換例
実際のプラットフォームのメッセージには、通常、画像、@メンション、返信などのリッチメディアコンテンツが含まれます。以下は、_convert_message_segments で複数のメッセージタイプを処理する例です:
def _convert_message_segments(self, raw_content: list) -> list:
"""プラットフォームのネイティブメッセージセグメントのリストを OneBot12 標準メッセージセグメントに変換する"""
segments = []
for item in raw_content:
item_type = item.get("type", "")
if item_type == "text":
segments.append({
"type": "text",
"data": {"text": item.get("content", "")}
})
elif item_type == "image":
file_url = item.get("url") or item.get("file_id", "")
segments.append({
"type": "image",
"data": {"file": file_url}
})
elif item_type == "at":
segments.append({
"type": "mention",
"data": {"user_id": item.get("target_id", "")}
})
elif item_type == "reply":
segments.append({
"type": "reply",
"data": {"message_id": item.get("reply_to_id", "")}
})
elif item_type == "at_all":
segments.append({"type": "mention_all", "data": {}})
else:
segments.append({
"type": "text",
"data": {"text": f"[未対応のメッセージタイプ: {item_type}]"}
})
return segments
よくある落とし穴
1. {platform}_raw フィールドの欠落
これは最もよくある間違いです。元のデータのフィールドが欠落すると、モジュールがプラットフォーム固有の情報にアクセスできなくなります。
base_event["myplatform_raw"] = raw_event # 必須!
base_event["myplatform_raw_type"] = event_type # 必須!
2. タイムスタンプ形式の誤り
OneBot12 標準では、time フィールドは Unix 秒単位のタイムスタンプ(整数)でなければなりません。プラットフォームがミリ秒のタイムスタンプや ISO 形式の文字列を返す場合は、変換が必要です:
import time
# ミリ秒 → 秒
"time": raw_event.get("timestamp", 0) // 1000
# ISO 文字列 → 秒
"time": int(time.mktime(time.strptime(raw_event["created_at"], "%Y-%m-%dT%H:%M:%S")))
3. self フィールドの欠落
self フィールドにはボット自身の情報が含まれ、user_id はボットのアカウント ID です。マルチボットのシナリオでは、このフィールドが極めて重要です:
"self": {
"platform": self.platform,
"user_id": raw_event.get("bot_id", ""), # ボット自身の ID
}
4. detail_type に非標準の値を使用している
detail_type は、private、group、friend_increase、group_member_increase など、OneBot12 標準で定義された値を使用しなければなりません。プラットフォーム固有の命名は使用しないでください。
5. ラウンドトリップの一貫性
Converter が生成するメッセージセグメントタイプが、Send 側がサポートするメソッドと対応していることを確認してください。たとえば、Converter がプラットフォームの画像メッセージを {"type": "image", ...} に変換するなら、Send 側の Image() メソッドは画像の送信を処理できる必要があります。
ベストプラクティス
- 常に元のデータを保持する:
{platform}_rawフィールドは省略できません - 標準メッセージセグメントを使用する:プラットフォームのメッセージはできる限り OneBot12 標準のメッセージセグメントに変換します
- detail_type を適切に設定する:標準タイプ(
private/group/channelなど)を使用し、独自定義はしないでください - エッジケースを処理する:元のイベントには一部のフィールドが欠けている可能性があるため、
.get()を使い適切なデフォルト値を提供します - パフォーマンスへの配慮:
convert()はすべてのイベントで呼び出されるため、その中で時間のかかる処理を実行することは避けてください
関連ドキュメント
アダプター開発パスを続ける
- アダプターのコア概念 - アダプター全体のアーキテクチャ
- SendDSL 詳解 - 逆変換(送信方向)
正式な仕様に従う
- イベント変換標準 - 正式なイベント変換仕様
- セッションタイプシステム - セッションタイプのマッピングルール