逆引き:チャンネル・ロール・メンバー操作
チャンネル作成、権限上書き、ロール付与、BAN/Kick、User/Member取得、cache、GBAN対象確認を整理します。
この記事で分かること
- 作成先カテゴリとチャンネル種別を分ける
- カテゴリ同期と個別上書きを確認する
- 転送/グローバルチャット対象を固定する
- 削除・移動前に復旧情報を残す
- Manage Rolesとロール階層を見る
- 名前指定よりID/mentionで対象を固定する
コミュニティの相談ログを匿名化・一般化し、チャンネル・ロール・メンバー操作の詰まりどころを整理した逆引きです。
チャンネル作成・権限上書き
作成先とチャンネル種別
TextChannel、VoiceChannel、Forum、Threadなどの作成先を分けます。
作成先を決める
チャンネル作成はguild直下、カテゴリ配下、既存チャンネル配下のthreadなどで必要な情報が変わります。category id、parent id、type、名前、topicを設定値として扱います。
種別ごとの差を見る
テキスト、ボイス、フォーラム、スレッドでは作成API、親チャンネル、権限継承、利用者に見える状態が違います。実装前にどの種別を作るか固定します。
確認ポイント
- guild id
- channel type
- parent/category id
- 作成後のchannel id
参考(公式ドキュメント)
転送・グローバルチャットの対象チャンネル
特定チャンネルへ転送するBotの対象判定を固定します。
対象を設定値にする
発言元や転送先を名前で探すと、リネームや重複で壊れます。channel id、guild id、許可するチャンネル一覧を設定として持ちます。
ループを防ぐ
転送先で再度イベントを拾う、Bot自身の発言を拾う、別サーバーへ無制限に流すなどを避けるため、発言者、送信元、送信先をログに残します。
確認ポイント
- source channel
- target channel
- Bot自身の除外
- 失敗時のログ
参考(公式ドキュメント)
- https://docs.discord.com/developers/resources/message
- https://docs.discord.com/developers/resources/channel
カテゴリ同期と権限上書き
カテゴリと個別チャンネルのPermission Overwriteを分けます。
同期状態を見る
カテゴリ配下でも、個別チャンネルが同期していない場合は権限上書きが別になります。閲覧、送信、履歴閲覧、接続、管理をそれぞれ確認します。
変更前を残す
上書きを変えるBotは、変更前のoverwrites、対象role/user、変更後の値を管理ログに残します。失敗時に戻せる情報がないまま一括変更しないようにします。
確認ポイント
- 変更前overwrites
- 対象role/user
- allow/deny
- 変更者
参考(公式ドキュメント)
- https://docs.discord.com/developers/resources/channel
- https://docs.discord.com/developers/topics/permissions
削除・移動の復旧設計
チャンネル削除、移動、並び替えを本番で行う前の確認です。
削除より無効化を優先する
削除は復旧が難しいため、まず閲覧停止、アーカイブ、名前変更などで影響を小さくできないか確認します。
監査とロールバック
誰が、どのチャンネルを、どの理由で、どこへ移動/削除したかを残します。Botの誤操作に備えて、対象IDと操作内容を実行前に確認できるようにします。
確認ポイント
- 対象channel id
- 移動先category id
- 実行者
- audit log
参考(公式ドキュメント)
- https://docs.discord.com/developers/resources/channel
- https://docs.discord.com/developers/resources/audit-log
ロール付与・BAN/Kick権限
ロール階層とManage Roles
ロール付与が失敗する時の基本確認です。
階層はAdministratorでも消えない
BotにAdministratorがあっても、Bot自身の最上位ロールより上または同じ高さのロールは操作できません。対象ロールと対象メンバーのロール位置を分けます。
権限と対象を分ける
Manage Roles権限、Botロール位置、付与したいロール、対象Member、利用者の実行権限を別々に確認します。
確認ポイント
- Manage Roles
- Botロール位置
- 対象ロール位置
- 対象Member
参考(公式ドキュメント)
- https://docs.discord.com/developers/topics/permissions
- https://docs.discord.com/developers/resources/guild
名前指定よりID/mentionを使う
ロール名・ユーザー名指定が不安定な時の確認です。
名前は重複する
ユーザー名、表示名、ロール名、チャンネル名は重複や変更があり得ます。管理操作はID、mention、選択UIなど、曖昧さが少ない入力へ寄せます。
変換失敗を返す
対象が見つからない時は、候補を無制限に出さず、入力例と必要な権限を短く返します。管理ログには入力値、変換結果、失敗理由を残します。
確認ポイント
- ID/mention入力
- Role変換
- Member変換
- 失敗理由
参考(公式ドキュメント)
- https://docs.discord.com/developers/resources/guild
- https://docs.discord.com/developers/topics/permissions
BAN/Kick/Unbanの対象確認
BAN、Kick、UnbanをUser/Memberと権限に分けます。
対象の種類を分ける
Kickはguild内のMember、BAN/UnbanはUser IDでも扱う場面があります。対象がそのサーバー内にいるか、Botが対象を操作できるかを確認します。
理由と範囲を残す
BAN理由、削除対象メッセージ範囲、実行者、対象者、失敗時のHTTPエラーを管理ログへ残します。公開チャンネルへ個人情報を流さないようにします。
確認ポイント
- 対象User/Member
- Bot権限
- 理由
- 失敗時の例外
参考(公式ドキュメント)
- https://docs.discord.com/developers/resources/guild
- https://docs.discord.com/developers/topics/permissions
失敗時の返信と監査ログ
利用者向け返信と管理者向けログを分けます。
利用者には短く返す
権限不足、対象不明、ロール階層、Bot権限不足などを、利用者には短く安全に返します。秘密情報や対象の詳細を公開しません。
管理ログで原因を残す
管理者向けには実行者、対象、必要権限、現在の権限、HTTPステータス、例外名を残します。後から監査ログと照合できる粒度にします。
確認ポイント
- 実行者
- 対象ID
- 必要権限
- HTTP/例外
- audit log
参考(公式ドキュメント)
- https://docs.discord.com/developers/resources/audit-log
- https://docs.discord.com/developers/topics/permissions
User/Member取得・Intent/cache
UserとMemberを分ける
ユーザー情報が取れない時に最初に確認する前提です。
Userは全体情報
UserはDiscord全体のユーザーを表す情報で、サーバー内のロール、ニックネーム、権限、参加日時などは持ちません。
Memberはguild内情報
Memberは特定guild内のユーザー状態です。ロール、ニックネーム、権限、BAN/Kick対象、VC状態などはMemberとして扱います。
確認ポイント
- User ID
- Guild ID
- Member取得方法
- 対象guild
参考(公式ドキュメント)
- https://docs.discord.com/developers/resources/user
- https://docs.discord.com/developers/resources/guild
Guild Members Intentとcache/fetch
Member情報が空、見つからない、古い時の確認です。
Intentとcacheを分ける
member join/update/remove、大量取得、ロールやニックネームの取得はGuild Members Intentやライブラリのcacheに影響されます。Intent不足とcache未取得を混同しないようにします。
fetch範囲を決める
必要な時だけfetchし、全メンバー取得を前提にしすぎない設計にします。取得できない時は、利用者に入力例や対象サーバー内の条件を返します。
確認ポイント
- Portal側Intent
- コード側Intent
- cache有無
- fetch対象
参考(公式ドキュメント)
- https://docs.discord.com/developers/events/gateway
- https://docs.discord.com/developers/resources/guild
共通サーバー外の情報
Botが見えない場所のMember情報を前提にしない確認です。
参加しているguildを見る
Botが参加していないguildや、対象ユーザーと共通サーバーがない場合、Member情報やロール情報は前提にできません。User IDで取れる情報とMember情報を分けます。
所有確認や本人確認へ逃がす
共通サーバー外の情報が必要な場合は、OAuth2、本人が実行するコマンド、確認用の一時値など、Botが見える範囲で確認できる設計にします。
確認ポイント
- User情報
- Member情報
- 共通guild
- 本人操作
参考(公式ドキュメント)
- https://docs.discord.com/developers/resources/user
- https://docs.discord.com/developers/resources/guild
オンライン状態と最終発言
Presenceや最終活動を取得したい時の限界です。
Presenceは前提が重い
オンライン状態やカスタムステータスはGatewayイベントやIntent、cacheの前提に影響されます。必要性が低いなら保存や監視の範囲を減らします。
最終発言はBot側で記録する
全ユーザーの最終発言や最終オンラインを後から完全に取得するのではなく、Botが見えるチャンネルでイベントを受けた時点で必要最小限を記録する設計にします。
確認ポイント
- Presence Intent
- message event
- 記録対象チャンネル
- 保存期間
参考(公式ドキュメント)
BAN/Kick・GBAN対象確認
BAN/Kick/Unbanの対象種類
User IDとMember objectを混同しない確認です。
操作ごとに対象が違う
Kickはguild内のMemberを対象にし、BAN/UnbanはUser IDで扱える場面があります。対象がguild内にいるか、Botが見えるか、対象IDが正しいかを分けます。
対象確認をログへ残す
実行前にguild id、target user id、対象がMemberとして取得できたか、Botの権限とロール位置を管理ログへ残します。
確認ポイント
- guild id
- target user id
- Member取得
- Bot権限
参考(公式ドキュメント)
- https://docs.discord.com/developers/resources/guild
- https://docs.discord.com/developers/topics/permissions
共通サーバー外ユーザーのBAN
Botと共通サーバーにいないユーザーを扱う時の確認です。
Member情報に頼らない
共通サーバー外のユーザーはMemberとしてのロールやニックネームを前提にできません。BAN対象として扱える情報と、確認できない情報を分けます。
誤BANを防ぐ
ID入力、確認画面、理由、実行者、対象guildを明示し、名前だけで対象を決めないようにします。
確認ポイント
- User ID入力
- 対象guild
- 理由
- 確認ステップ
参考(公式ドキュメント)
- https://docs.discord.com/developers/resources/user
- https://docs.discord.com/developers/resources/guild
GBANをguildごとに確認する
複数サーバーBANの失敗を局所化します。
一括処理を分割する
GBANは対象guildごとに権限、ロール階層、Bot参加状態、対象ユーザーの状態が違います。全体成功/失敗だけでなくguild単位で結果を残します。
再試行できる形にする
失敗したguild、理由、HTTPエラー、権限不足を記録し、再実行時に成功済みguildを二重処理しないようにします。
確認ポイント
- guild単位結果
- HTTPステータス
- 権限不足
- 再試行対象
参考(公式ドキュメント)
- https://docs.discord.com/developers/resources/guild
- https://docs.discord.com/developers/topics/permissions
理由と監査ログ
モデレーション操作の説明責任を残します。
理由を短く安全に残す
BAN/Kick理由には公開してよい範囲だけを残し、個人情報や秘密情報を入れません。利用者向け返信と管理者向けログを分けます。
監査ログと照合する
実行者、対象者、guild、理由、成功/失敗、例外をBot側にも残し、DiscordのAudit Logと後から照合できる粒度にします。
確認ポイント
- 実行者
- 対象者
- 理由
- Audit Log
- 例外
参考(公式ドキュメント)
一次情報(公式ドキュメント)
- Discord Developer Documentation: Channel Resource
- Discord Developer Documentation: Permissions
- Discord Developer Documentation: Audit Log
- Discord Developer Documentation: Guild Resource
- Discord Developer Documentation: User Resource
- Discord Developer Documentation: Gateway