コンテンツにスキップ

Matrixルーム出力リファレンス

このリファレンスでは、output: matrixを使用して、選択したAdderイベントをMatrixルームへ通知する方法を説明します。出力はMatrix Client-Server APIのm.room.messageイベントとして、プレーンテキストのm.textメッセージを送信します。

次の項目を準備します。

  • 接続先MatrixホームサーバーのベースURL
  • メッセージ送信用のMatrixアクセストークン
  • AdderのMatrixユーザーが参加し、メッセージを送信できるルーム

アクセストークンはBearer認証情報です。YAML設定ファイルを保護し、トークンをログや共有設定には保存しません。Matrixユーザーには、各対象ルームへの参加権限とメッセージ送信権限が必要です。

次の例は、3種類のイベントを1つのMatrixルームへ送信します。

output: matrix
plugins:
output:
matrix:
homeserver-url: https://matrix.example.org
access-token: MATRIX_ACCESS_TOKEN
room-ids: "!roomid:example.org"
event-types: blocks,rollbacks,governance
キー説明
homeserver-url接続先MatrixホームサーバーのベースURL。リモート接続にはhttps://を指定します。HTTPはループバックアドレスへのテスト接続だけに使用できます。既定値は空です。
access-tokenMatrix APIのBearerアクセストークン。既定値は空です。
room-ids送信先ルームIDをコンマ区切りで指定します。既定値は空です。
event-types送信対象のイベント種別をコンマ区切りで指定します。

room-idsには、通常の!room:server.example形式のIDと、Matrix room version 12で使用するサーバーサフィックスなしの!roomid形式のIDを指定できます。Adderは設定したルームごとに、選択した各イベントを送信します。これにより、複数のルームへ同じ通知を配信できます。

event-typesには、blocks、transactions、rollbacks、governance、drep-registration、drep-update、drep-retirementを指定できます。未指定の場合、Adderはblocks、rollbacks、governanceを送信します。空の値やサポート対象外の値は設定エラーになります。

Adderは起動時に次の設定を検証します。

  • homeserver-urlは有効なHTTP URLでなければなりません。リモートのホームサーバーにはhttps://を使用します。http://はループバックアドレスのテストに限って許可します。
  • room-idsには少なくとも1つのルームIDを指定します。
  • 各ルームIDは!で始まり、空白を含めることはできません。
  • room version 12のIDでは、従来の:serverサフィックスを省略できます。

設定値の検証は、アクセストークンが有効であること、Matrixユーザーがルームに参加していること、または送信権限を持つことを確認しません。起動後のライブチェックで、実際のルーム権限とAPI接続を確認します。

Adderは、選択した各イベントをルームごとに次のエンドポイントへ送信します。

PUT /_matrix/client/v3/rooms/{room}/send/m.room.message/{txnId}
Authorization: Bearer <access-token>
Content-Type: application/json

リクエスト本文は次のJSON形式です。

{
"msgtype": "m.text",
"body": "Adder <type>\n<event-json>"
}

bodyにはAdder <type>の行と、続くイベントJSONを設定します。m.room.messageは送信イベントの種類、m.textはメッセージ本文の種類を示します。Adderは各ルームと各イベントの組み合わせに対して、adder-<randomPrefix>-<counter>形式のtxnIdを生成します。

Matrixが送信リクエストを受け入れると、そのルームへの配信は成功します。この応答は、ルーム内のすべてのメンバーがメッセージを表示または処理したことを確認するものではありません。複数のルームを設定した場合、Adderは各ルームへの配信を個別に処理します。

Adderは一時的な失敗だけを上限付きで再試行します。既定の最大再試行回数は3です。再試行には指数バックオフを使用し、同じルームとイベントの再試行では同じtxnIdを使います。これにより、再試行時に新しいトランザクションIDを発行しません。

次の失敗は再試行の対象です。

  • ネットワークエラーまたはHTTPリクエストの作成、送信エラー
  • HTTP 408
  • HTTP 5xx
  • HTTP 429

HTTP 429では、AdderはRetry-Afterを次の形式で解釈します。

  • 秒数を表す小数値
  • HTTP日時

標準のRetry-Afterを利用できない場合、Adderは互換性のためレスポンスの旧形式のretry_after_msヒントも解釈します。Retry-Afterまたはretry_after_msが示す待機時間は最大1分です。1分を超える待機時間は再試行せず、配信エラーとして扱います。

HTTP 408、HTTP 5xx、HTTP 429以外のHTTP 4xxは永続的な失敗として扱い、再試行しません。最大再試行回数に達した一時的な失敗も、配信失敗として扱います。

配信エラーはoutput.matrixコンポーネントでログに記録し、AdderのエラーチャネルへTrySendErrorで報告します。エラーチャネルの利用側は、ログ監視やプロセス監視にこの通知を利用できます。

Adderの停止処理は、進行中のMatrixリクエストをキャンセルします。出力には永続キューや耐久性のある再生機能がありません。停止または再起動の時点で処理中のイベントや未送信イベントが残っていても、Adderは後から自動的に再送しません。

テストルームでのライブチェック

Section titled “テストルームでのライブチェック”

本番ルームを設定する前に、専用のテストルームで次の手順を実行します。

  1. Matrixユーザーをテストルームへ参加させ、メッセージを送信できる権限を付与します。
  2. homeserver-url、access-token、テストルームの!で始まるroom-idsを設定します。
  3. event-typesを1種類に絞り、Adderを起動します。
  4. 設定したイベントを発生させ、テストルームにm.room.message形式のメッセージが表示されることを確認します。
  5. 複数ルームを設定する場合は、同じイベントが各ルームに届くことを確認します。
  6. output.matrixのログとエラーチャネルを確認し、HTTPエラーや権限エラーがないことを確認します。

Doc Holiday logo

Docs authored by Doc Holiday