managing-managed-event-subscription

ManagedEventSubscription の管理

ManagedEventSubscription メタデータを作成、読み取り、更新、削除します。これは、マネージド再生追跡を使ってプラットフォームイベントチャネルを永続的に購読するための Salesforce の構成要素です。

対象範囲

• 対象範囲内：作成、読み取り、更新、削除の操作における .managedEventSubscription-meta.xml ファイルの生成と変更
• 対象範囲外：基盤となるプラットフォームイベント（__e）チャネル自体の作成、Flow ベースまたは Apex ベースのイベント購読、組織へのメタデータのデプロイ
• 生成するファイルは 1 つだけです — .managedEventSubscription-meta.xml ファイルです。参照先のプラットフォームイベントオブジェクトや、その他のメタデータ型は生成しないでください。

---

確認事項

生成を始める前に、以下が明確でない場合は確認してください。

• トピック名は何ですか？（形式については references/topic-name-formats.md を参照してください）
• 開発者名は何ですか？（作成では必須です。英数字とアンダースコアのみ使用でき、スペースは使えません。読み取り／更新／削除では、Id が分かっていれば省略できます）
• ラベル（人が読みやすい名前）は何ですか？
• デフォルトの再生プリセットは何ですか？ — LATEST（デフォルト）または EARLIEST
• エラー回復時の再生プリセットは何ですか？ — LATEST（デフォルト）または EARLIEST
• 初期状態はどうしますか？ — RUN（有効）または STOP（無効）。（デフォルト：RUN）

---

必須入力

続行する前に、以下を収集または推定してください。

• 操作：作成、読み取り、更新、または削除
• DeveloperName：作成では必須（ファイル名になります）。読み取り／更新／削除では、代わりに Id を指定する場合は省略できます
• Id：Tooling API のレコード Id — DeveloperName の代わりに、読み取り／更新／削除の対象となる購読の識別に使用できます
• label：人が読みやすいラベル（スペースを含めることができます）
• topicName：イベントチャネルのパス — 有効な形式（プラットフォームイベント、変更イベント、カスタムチャネル）については references/topic-name-formats.md を参照してください
• defaultReplay：LATEST または EARLIEST（デフォルト：LATEST）
• errorRecoveryReplay：LATEST または EARLIEST（デフォルト：LATEST）
• state：RUN または STOP（デフォルト：RUN）— PAUSE はプラットフォーム内部での使用に限られており、INVALID_INPUT で拒否されます
• version：Metadata API のバージョン（デフォルト：組織の API バージョンに合わせます。例：67.0）

---

ワークフロー

作成

1. 入力を収集する — DeveloperName、label、topicName、defaultReplay、errorRecoveryReplay、state、version を確認します。省略されたフィールドにはデフォルト値を適用します。DeveloperName が指定されていない場合はユーザーに確認し、label から導出しないでください。
2. トピックの存在を確認する — 続行する前に、イベントチャネルがすでに組織内に存在することをユーザーに確認します。プラットフォームイベントオブジェクトを自分で生成しないでください。このスキルの対象範囲外です。まだ存在しないとユーザーが回答した場合は、そこで中断し、まず generating-platform-event スキルを使って作成するよう案内してから、ここに戻ってください。
3. テンプレートを読み込む — assets/managed-event-subscription-template.xml を開始構造として読み込みます。
4. ファイルを生成する — ユーザーが指定した値を入力し、managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml を生成します。
5. 検証する — 出力を提示する前に、以下のチェックリストを実行します。
6. 購読方法を案内する — デプロイ後、Pub/Sub API の ManagedSubscribe RPC 呼び出しでは、DeveloperName またはレコードの Id を使って購読を識別できます。Id を取得するには、Tooling API 経由で次を実行します：SELECT Id, DeveloperName FROM ManagedEventSubscription WHERE DeveloperName='<DeveloperName>'

読み取り

1. 購読を特定する — Id または DeveloperName を受け付けます。両方が指定されている場合は Id を優先します。
2. ファイルパスを表示する — managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml（DeveloperName が分かっている場合）。
3. 取得して表示する — 現在の XML コンテンツを読み取り、提示します。

更新

1. サブスクリプションを特定する — Id または DeveloperName のいずれかを受け付けます。両方が指定されている場合は、Id を優先します。
2. 既存のファイルを読み込む — 変更する前に、現在の内容を読み込みます。
3. 変更を適用する — 指定されたフィールドのみを更新し、その他のフィールドはすべて保持します。
4. references/update-constraints.md を読む — 作成後に変更できないフィールドを確認します。
5. 検証する — 出力を提示する前に、以下のチェックリストを実行します。

削除

1. サブスクリプションを特定する — Id または DeveloperName のいずれかを受け付けます。続行する前に、ユーザーに確認します。
2. 警告する — ManagedEventSubscription を削除すると、リプレイトラッキングの状態が完全に削除されます。
3. 削除手順を提示する — ファイルの削除方法と、destructiveChanges.xml を使用した破壊的変更のデプロイ方法を説明します。
4. references/delete-guide.md を読む — 破壊的デプロイの手順を確認します。

---

ルール／制約

制約	理由
<topicName> は有効なパスプレフィックスを使用する必要があります	プラットフォームイベントでは /event/Name__e、変更イベントでは /data/Name を使用します。すべての形式については references/topic-name-formats.md を参照してください
<defaultReplay> と <errorRecoveryReplay> は LATEST または EARLIEST である必要があります	有効な列挙値はこれらのみです。それ以外の値を指定すると、メタデータ検証に失敗します
<state> は RUN または STOP である必要があります	PAUSE はプラットフォーム内部での使用に予約されています。API は INVALID_INPUT: You can create a managed event subscription state field only to RUN or STOP で拒否します
必須の 6 つの要素をすべて含める必要があります	topicName、defaultReplay、errorRecoveryReplay、label、state、version はすべて必須です。いずれかを省略すると、デプロイエラーが発生します
DeveloperName は組織内で一意である必要があります	名前が重複すると、DUPLICATE_DEVELOPER_NAME エラーが発生します
<namespacePrefix>、<id>、または <createdDate> を含めないでください	これらは読み取り専用のプラットフォームフィールドです。含めると、パッケージ化されていない組織ではデプロイに失敗します

---

注意点

問題	対処方法
デプロイ時に The topicName field is invalid が発生する	形式が間違っているか、イベントが組織に存在しません。正しいパスについては references/topic-name-formats.md を参照してください
削除後に再作成するとリプレイ状態が失われる	削除すると保存されたリプレイ位置が破棄されます。再作成すると defaultReplay から開始するため、削除後に同じ DeveloperName を再利用しないでください
SOQL クエリで INVALID_TYPE が発生する	ManagedEventSubscription は Tooling API 経由でのみクエリ可能で、標準の SOQL ではクエリできません
大量のイベントが流れるチャネルで EARLIEST リプレイを使用する	有効化時に最大 72 時間分のバックログ再生が発生する可能性があります。必ずユーザーに確認してください
古い組織でメタデータがサポートされていない	ManagedEventSubscription には API v60.0 以降が必要です。組織の API バージョンを確認してください
生成された XML に eventChannel または isActive が含まれている	これらは誤ったフィールド名です。代わりに topicName と state（RUN／STOP）を使用してください
生成された XML で PAUSE 状態が指定されている	PAUSE はプラットフォーム内部での使用に予約されており、INVALID_INPUT で拒否されます。RUN または STOP のみを使用してください
Pub/Sub API 用のサブスクリプションの特定方法がわからない	ManagedSubscribe RPC では DeveloperName とレコードの Id のどちらも使用できます。必要に応じて、Tooling API で Id を取得します：SELECT Id FROM ManagedEventSubscription WHERE DeveloperName='<name>'
Pub/Sub API に変更がすぐに反映されない	作成、更新、削除の後、新しい設定が Pub/Sub API に反映されるまで最大約 2 分かかることがあります。ManagedSubscribe が NOT_FOUND を返した場合は、待ってから再試行してください

---

検証チェックリスト

生成した XML を提示する前に、次の項目を確認します。

• <topicName> は references/topic-name-formats.md に記載されている有効なパス形式に従っていますか？（/event/Name__e、/data/NameChangeEvent、/data/ChangeEvents、/event/Name__chn、/data/Name__chn）
• <defaultReplay> は正確に LATEST または EARLIEST ですか？
• <errorRecoveryReplay> は正確に LATEST または EARLIEST ですか？
• <state> は正確に RUN または STOP ですか？（ユーザーが作成したサブスクリプションでは PAUSE は無効です）
• <label> に値が設定されていますか？
• <version> が含まれていますか（例：67.0）？
• 読み取り専用フィールド（<id>、<createdDate>、<namespacePrefix>）は含まれていませんか？
• ファイル名は DeveloperName と完全に一致していますか？

---

出力要件

• 作成／更新：managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml — 生成するファイルはこれだけです
• 削除：ファイルを削除し、destructiveChanges.xml を介してデプロイする手順
• 読み取り：既存ファイルの内容を表示

---

スキル間の連携

必要な作業	委任先
サブスクライブするプラットフォームイベントチャネル（__e）を作成する	generating-platform-event スキル
Flow（プロセス自動化）を介してサブスクライブする	generating-flow スキル
メタデータを org にデプロイする	deploying-metadata スキル

---

参照ファイル一覧

ファイル	参照するタイミング
assets/managed-event-subscription-template.xml	新しいサブスクリプションを生成する前 — 開始構造として使用します
references/topic-name-formats.md	<topicName> を設定するとき — プラットフォームイベント、変更イベント、カスタムチャネルを扱います
references/update-constraints.md	更新ワークフロー中 — 作成後に変更できないフィールドを確認します
references/delete-guide.md	削除ワークフロー中 — 破壊的変更のデプロイ手順を確認します