ErisPulse アダプターの標準化された返却値仕様
Tip
この記事を読むタイミング:アダプター内で call_api / Send / Request の返り値を実装する際に、返却値の構造と返却コードが ErisPulse の標準に準拠しているか確認する必要がある場合、または特定の retcode の意味を確認したい場合に、本記事を参照してください。必要がない場合は飛ばしてください。
1. 説明
なぜこの規格があるのでしょうか?
各プラットフォームの送信インターフェースが一貫性とOneBot12との互換性を確保するため、ErisPulseアダプターはAPIレスポンス形式においてOneBot12が定義するメッセージ送信返却構造の標準を採用しています。
ただしErisPulseのプロトコルにはいくつかの特殊な定義があります:
- 基本フィールドにおいて、message_idは必須ですが、OneBot12の標準にはこのフィールドはありません。
- 返却内容には、{platform_name}_raw フィールドを追加する必要があります。このフィールドには、元のレスポンスデータを格納します。
2. 基礎レスポンス構造
すべてのアクションレスポンスには、以下の基本フィールドを含める必要があります。
| フィールド名 | データ型 | 必須 | 説明 |
|---|---|---|---|
| status | string | はい | 実行ステータス。"ok"または"failed"のいずれかに設定する必要があります |
| retcode | int64 | はい | 戻り値コード。OneBot12の戻り値コード規則に従います |
| data | any | はい | レスポンスデータ。成功時はリクエスト結果を含み、失敗時はnull |
| message_id | string | はい | メッセージID。メッセージを識別するためのもので、存在しない場合は空文字列 |
| message | string | はい | エラーメッセージ。成功時は空文字列 |
| {platform_name}_raw | any | いいえ | 元のレスポンスデータ |
オプションフィールド:
| フィールド名 | データ型 | 必須 | 説明 |
|---|---|---|---|
| echo | string | いいえ | リクエストにechoフィールドが含まれている場合、その値をそのまま返します |
3. 完全なフィールド仕様
3.1 一般的なフィールド
成功時のレスポンス例
{
"status": "ok",
"retcode": 0,
"data": {
"message_id": "1234",
"time": 1632847927.599013
},
"message_id": "1234",
"message": "",
"echo": "1234",
"telegram_raw": {...}
}
失敗時のレスポンス例
{
"status": "failed",
"retcode": 10003,
"data": null,
"message_id": "",
"message": "必要なパラメータが不足しています: user_id",
"echo": "1234",
"telegram_raw": {...}
}
3.2 戻り値コードの仕様
0 成功(OK)
- 0: 成功(OK)
1xxxx 動作リクエストエラー(Request Error)
| エラーコード | エラー名 | 説明 |
|---|---|---|
| 10001 | Bad Request | 無効な動作リクエスト |
| 10002 | Unsupported Action | 対応していない動作リクエスト |
| 10003 | Bad Param | 無効な動作リクエストパラメータ |
| 10004 | Unsupported Param | 対応していない動作リクエストパラメータ |
| 10005 | Unsupported Segment | 対応していないメッセージセグメントの種類 |
| 10006 | Bad Segment Data | 無効なメッセージセグメントパラメータ |
| 10007 | Unsupported Segment Data | 対応していないメッセージセグメントパラメータ |
| 10101 | Who Am I | ロボットアカウントが指定されていません |
| 10102 | Unknown Self | 知らないロボットアカウント |
2xxxx 動作ハンドラーエラー(Handler Error)
| エラーコード | エラー名 | 説明 |
|---|---|---|
| 20001 | Bad Handler | 動作ハンドラーの実装エラー |
| 20002 | Internal Handler Error | 動作ハンドラーが実行中に例外をスローしました |
3xxxx 動作実行エラー(Execution Error)
| エラーコード範囲 | エラー種別 | 説明 |
|---|---|---|
| 31xxx | Database Error | データベースエラー |
| 32xxx | Filesystem Error | ファイルシステムエラー |
| 33xxx | Network Error | ネットワークエラー |
| 34xxx | Platform Error | ロボットプラットフォームエラー |
| 35xxx | Logic Error | 動作ロジックエラー |
| 36xxx | I Am Tired | 実装が作業を中止することを決定しました |
保留エラーセグメント
- 4xxxx、5xxxx: 保留セグメント、使用しないでください
- 6xxxx~9xxxx: 他のエラーセグメント、実装が独自に使用するためのものです
4. 実装要件
- すべてのレスポンスは、status、retcode、data、message フィールドを含む必要があります。
- リクエストに非空の echo フィールドが含まれている場合、レスポンスには同じ値の echo フィールドが含まれている必要があります。
- 戻り値コードは OneBot12 規格に厳密に従う必要があります。
- エラーメッセージ(message)は人間に読みやすい説明である必要があります。
4.1 レスポンス構築ヘルパー:make_response / make_error
アダプタは、BaseAdapter 上の 2 つのヘルパーを使用して標準レスポンスを一貫して構築します。dict を手動で記述する必要はありません。
# 成功(send / call_api / _do_accept など、すべての標準レスポンスを返す位置)
return self.make_response(
data=result, # レスポンスデータ
message_id=result.get("message_id", ""),
raw=result, # プラットフォームの元のレスポンス → 自動的に {platform}_raw フィールドに追加
)
# 失敗(status は固定で "failed")
return self.make_error(
retcode=34100, # デフォルトは 34600(SDK Failure);プラットフォームエラーは独自の 34xxx を渡す
message="プラットフォームのリスク管理が拒否しました",
raw=response,
)
| ヘルパー | シグネチャ | 意味 |
|---|---|---|
make_response |
(*, status="ok", retcode=0, data=None, message_id="", message="", raw=None) |
標準構造に従ってレスポンスを構築します。raw が None でない場合、自動的に {platform}_raw キーを追加します(プラットフォーム名は self._platform から取得) |
make_error |
(retcode=34600, message="", raw=None) |
make_response(status="failed", ...) のショートカットです |
手動で等価な dict を記述することも合法です(構造が一致していれば)。ヘルパーの価値は、
{platform}_rawのプラットフォーム名の自動連結と、フィールドの漏れがないことです。
5. 拡張仕様
ErisPulse は OneBot12 標準の返却構造に以下の拡張を行っています。
5.1 message_id 必須フィールド
OneBot12 標準では message_id は data オブジェクト内にあり、必須ではありません。ErisPulse ではこれをトップレベルの必須フィールドに昇格しています:
message_idを取得できない場合は空文字列""に設定するmessage_idが常に存在することを保証し、モジュールは null チェックを行う必要がない
両側を区別すること:本節のトップレベル昇格はアクション応答(出力)にのみ適用されます。入力 message イベントの
message_idは OneBot12 基準のトップレベル必須フィールドです。詳細はイベント変換標準を参照してください。
5.2 {platform}_raw 原始応答フィールド
返却値には、プラットフォームの原始応答データの完全なコピーを格納する {platform}_raw フィールドを含める必要があります:
{
"status": "ok",
"retcode": 0,
"data": {"message_id": "1234", "time": 1632847927},
"message_id": "1234",
"message": "",
"telegram_raw": {
"ok": true,
"result": {"message_id": 1234, "date": 1632847927, ...}
}
}
要件:
{platform}_rawは原始応答の深コピーであり、参照ではないplatformはアダプタ登録時のプラットフォーム名と完全一致(大文字小文字を区別)- 原始応答のエラーメッセージも保持し、デバッグに利用できるようにする
5.3 フレームワーク拡張返却コード(34xxx プラットフォームエラーセグメントの下3桁カスタム)
OneBot12 規格では、実装者が 3xxxx の下3桁をカスタムに使用できます。34xxx の意味は Platform Error(ロボットプラットフォームエラー、例えばプラットフォーム制限により失敗した場合)です。34xxx 内部では、役割に応じて以下の層に分けて使用します:
| 下3桁セグメント | 所属 | 用途 |
|---|---|---|
340xx |
アダプタ実装 | リクエスト操作族(Request Not Found / Already Handled / Not Supported / Permission Denied、request-action-spec §7 参照) |
341xx~345xx |
アダプタ実装 | プラットフォーム側の権限 / リスク管理 / アカウント制限等のエラー(実装者が下3桁を独自に定義し、原始エラーは {platform}_raw に格納) |
346xx |
ErisPulse フレームワーク(予約済み) | フレームワーク自身によるブロックと一般的な失敗、アダプタ/モジュールは使用しない |
347xx~349xx |
アダプタ実装 | その他のプラットフォーム実行エラー |
ErisPulse フレームワークで現在使用している 346xx エラーコードは以下の通りです:
| エラーコード | エラーネーム | 説明 |
|---|---|---|
| 34600 | SDK Failure | フレームワークの一般的な失敗(make_error() のデフォルト返却コード) |
| 34601 | Action Denied | 出力アクションがスコープ scope.actions により禁止されているため、呼び出しは行われず、直接この応答を返す |
役割の区別:
34601はフレームワークが呼び出し前にブロックした場合(モジュールはそもそもアクションを発行する資格がない)です。一方、34004/34xxxプラットフォームコードはアクションは発行されたがプラットフォームが拒否した場合(Bot に権限がない、リスク管理対象など)です。モジュールが権限問題を判断する際には、この2つを同時にチェックする必要があります:まず34601(モジュール自身が scope で禁止されているか)、次に34xxx(プラットフォーム側の制限)を確認します。
返却構造は §2 の標準失敗応答に準拠します:
{
"status": "failed",
"retcode": 34601,
"data": null,
"message_id": "",
"message": "action 'send' denied by scope.actions"
}
5.4 アダプタ実装チェックリスト
-
status,retcode,data,message_id,messageフィールドを含む - 返却コードは OneBot12 規格に準拠する(§3.2 参照)
-
message_idが常に存在する(取得できない場合は空文字列) -
{platform}_rawにプラットフォームの原始応答データを含む
6. 注意事項
- 3xxxxエラーコードについては、下位3桁は実装側で独自に定義可能
- 予約エラーセグメント(4xxxx、5xxxx)の使用を避けること
34600/34601は ErisPulse フレームワークが予約するコード(§5.3参照)であり、アダプタ/モジュールは使用しないこと- エラーメッセージは簡潔かつ明瞭にし、デバッグに役立つようにすること
次のステップ
- 各DSLの戻り値に対応する照会:APIアクション標準(標準アクションのdataフィールド)、リクエスト操作規格(リクエスト操作の34001-34004拡張)、送信メソッド規格(送信失敗時の降格意味)
- 権限関連の失敗のトラブルシューティング:まず
34601(モジュールがscopeによって禁止されている、フレームワークが呼び出し前にブロックする、§5.3を参照)、次に34xxx(アクションは発行されたが、プラットフォーム側で拒否された)を確認する