integration-eventing-subscription-configure

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）

---

必要な入力

処理を進める前に、情報を収集するか推定してください。

• Operation: create、read、update、または delete
• 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. トピックの存在を確認する — 続行する前に、イベントチャネルがすでに組織に存在することをユーザーに確認します。プラットフォームイベントオブジェクトを自分で生成してはいけません。このスキルの対象外です。まだ存在しないとユーザーが回答した場合は、作業を中止し、まず platform-custom-object-generate スキルを使って作成するよう案内してから、ここに戻るよう伝えてください。
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）を作成する	platform-custom-object-generate skill
Flow（プロセス自動化）でサブスクライブする	automation-flow-generate skill
メタデータを組織にデプロイする	platform-metadata-deploy skill

---

参照ファイル一覧

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