サブスクリプションとは
CPaaS Xでは、サブスクリプションは、通知をトリガーするイベントとその通知の送信先を決定するルールを定義します。サブスクリプションは、条件と配信ターゲットを指定することで、チャネルや製品間のコミュニケーションアクティビティを監視するのに役立ちます。
各サブスクリプションには次のものが含まれます：
- Category (カテゴリー) と Event types (イベントの種類)：選択したカテゴリーの通知をトリガーするイベントの種類を定義します。
- 通知プロファイル：通知の送信先 (ウェブフックURL) と配信方法を指定します。認証が必要な場合は、プロファイルに認証設定を適用できます。
- (任意) Filters (フィルター)：一致するイベントの範囲を絞り込みたい時に使用します。アプリケーション、エンティティ、ユーザーまたはリソースでフィルター処理できます。
- (任意) Authentication settings (認証設定) と Certificates (証明書)：ウェブフックのセキュリティを高めたい時に使用します。認証設定では、通知の送信時にシステムが認証する方法を定義します。これらの設定は任意であり、ウェブフックで認証が求められる場合にのみ必要になります。
サブスクリプション、通知プロファイル、認証設定や証明書を作成したい時、サブスクリプション API (opens in a new tab) を使用するか、NTT CPaaSのWeb インターフェイス (opens in a new tab)上で Developer Tools (開発者ツール) > Subscription Management (サブスクリプション管理) に移動します。
イベントと通知
通信チャネル (SMS、WhatsApp、RCS、メールなど) を介して送信されるすべてのコールまたはメッセージは、1つ以上の イベント のトリガーになる可能性があります。これらのイベントは、次のようなメッセージのステータスまたはユーザーのアクションに変更があったことを示します：
- Delivery (配信)：メッセージが正常に配信されたことを示します (
DELIVERY) - Click (クリック)：ユーザーがリンクをクリックしたことを示します (
CLICK) - Inbound message (インバウンドメッセージ)：ユーザーがメッセージに対して返信したことを示します (
INBOUND_MESSAGE) - Identity change (IDの変更)：ステータスが更新されたことを示します (例：WhatsApp の
IDENTITY_CHANGEなど)
通知は、これらのイベントが発生した時にウェブフックに送信される HTTPリクエストです。これにより、システムはチャネル全体のリアルタイムアクティビティに対応できます。
一部のイベントは、特定のメッセージに関連付けられていません。例えば：
- キャンペーンまたは送信者のステータスの変更
- 番号検索やモバイルIDなどのツールからの更新
- Momentsの外部APIトリガー
イベント通知を受信するには、チャネルごとに少なくとも1つのサブスクリプションを定義する必要があります。異なるイベントの種類を異なるウェブフックにルーティングする場合は、複数のサブスクリプションを作成できます。
カテゴリーごとに利用可能なイベントの包括的なリストについては、イベントサブスクリプション について詳述しているドキュメントをご参照ください。
チャネルとカテゴリー
サブスクリプションは、イベントのソースまたは種類を定義する カテゴリー 別に整理されています。
カテゴリーには次のものが含まれます：
| チャネル | 番号と送信者 | ツール |
|---|---|---|
| Apple Messages for Business メール Facebook Messenger Kakao – Alim Kakao – Chingu LINE モバイルプッシュ通知 RCS SMS MMS Viber Zalo Voice と WebRTC オープンチャネル | 登録 モバイルID 番号検索 | ブロックリスト 顧客エンゲージメント |
各カテゴリーには、サポートされているイベントの独自のリストが用意されています。完全なリファレンスについては、イベントサブスクリプション について詳述しているドキュメントをご参照ください。
サブスクリプションのフィルターと対象範囲
サブスクリプションには、対象範囲を制限するためのフィルターをオプションとして含めることができます。サポートされているフィルターの種類は以下のを含みます：
- Users (ユーザー)
- Entity (エンティティ)
- Application (アプリケーション)
- Resources (リソース)
サブスクリプションは、通知を送信する基準を定義します。定義する基準は、ごく一般的なものから非常に具体的なものまで含めることができます。例えば、特定のイベントについて通知を送信したり、アプリケーションやエンティティなどの他の基準に基づいて通知を送信したりするようにサブスクリプションを構成できます。チャネル全体とすべてのイベントを適用対象とするサブスクリプションを作成する場合は、フィルタリングオプションを空のままにします。
各サブスクリプションには、通知をどこに送信し、どのような設定を使用するかを定義する 通知プロファイル を含める必要があります。例えば、プロファイルには、ウェブフックのURLと想定コンテンツに関する詳細を含めることができます。また、オプションとして、認証設定 を適用して、通知の配信時にシステムが認証する方法を定義することもできます。
通知プロファイルと認証設定は、すべて一から定義することもできますし、既存のセットアップ内容をIDで参照して定義することも可能です。
ここで、複数の通知プロファイル間で認証設定を再利用する方法と、それらのプロファイルをサブスクリプションに紐づける方法の例を示します。
フィルターを使用しない場合、サブスクリプションは選択したカテゴリーとチャネルの すべてのイベントに適用されます。
サブスクリプションを作成する際、同じリクエストで通知プロファイルと認証設定の両方を構成できます。または、個別に作成して再利用することも可能です。ウェブフックのエンドポイントを保護するために、少なくとも基本認証を使用することをお勧めします。
また、通知を受信するチャネルごとにサブスクリプションを作成しておくことも重要です。
通知プロファイルはサブスクリプションとは別に管理でき、認証設定はプロファイルとは別に管理できます。この柔軟性により、これらのオブジェクトを個別に作成し、新しいサブスクリプションを作成する時にIDを参照して再利用できます。
各サブスクリプションは一意である必要があります。同じサブスクリプションを2つ作成することはできません：
- チャネル
- イベントの種類
- フィルターの値
複製を作成しようとすると、検証エラーが返されます。これにより、次のことが保証されます：
- 複数の同一サブスクリプションをトリガーするイベントはありません。
- 通知ロジックは明確で、トラブルシューティングが容易です。
1つのイベントで複数の同一サブスクリプションがトリガーされることはありません。
フィルターの活用法に関するベストプラクティス
アプリケーション (applicationId) やエンティティ (entityId) などのフィルターを使って、サブスクリプションをトリガーするイベントを制御できます。こうしたフィルターは、イベントカバレッジを微調整したり、冗長的または曖昧な構成を回避したりしたい時に使用します。
イベントカバレッジの定義
- フィルターを使って、サブスクリプションの対象範囲を広げたり、狭めたりすることができます。例えば、
applicationIdを設定すると、そのアプリケーションのイベントのみが対象になります。フィルターを空のままにすると、選択したカテゴリーとチャネルのすべてのイベントが含まれます。この柔軟性により、サブスクリプションを正確なニーズに合わせて調整できます。
サブスクリプションの一意性の確保
- どのサブスクリプションも他と異なる個別のものでなければなりません。チャネル、イベントの種類やフィルター値がどれも同じであるサブスクリプションを2つ作成した場合、システムは2番目に作成されたサブスクリプションを拒否します。そうすることにより、システムは同じ処理を重複することを防ぎ、各サブスクリプションの構成を整理された状態で保てるようにします。
基準の一致
- サブスクリプションは、フィルタリングの基準がすべてインバウンドイベントに当てはまる場合にのみトリガーされます。例えば、
applicationId=AppBとentityId=Template123を使用する場合、サブスクリプションはそのアプリケーションとエンティティからのイベントのみと一致します。この正確なターゲティングにより、該当するイベントの更新情報のみを確実に受け取ることができます。
1つのイベント、1つのサブスクリプション
- 各イベントは 1つのサブスクリプションのみと一致します。これにより、一貫性のある配信が保証され、処理の重複が回避され、トラブルシューティングが容易になります。
サブスクリプションの対象範囲を定義することで、関連するイベントのみに集中し、透明性のある通知システムを維持できます。ビューを1つのエンティティに絞り込む場合でも、チャネル全体を網羅するように広げる場合でも、これらのガイドラインは、サブスクリプションが適切な情報を的確なタイミングで配信できるようにするのに役立ちます。
サブスクリプションの階層
サブスクリプションは、相互接続されたコンポーネントのシステムの一部です：
- カテゴリー／チャネルは、複数の サブスクリプション を持つことができます。
- 各サブスクリプションには、通知プロファイル が含まれている必要があります。
- 通知プロファイルには、認証設定を含めることができます。
- 通知プロファイルに 証明書 を追加して、mTLS (相互TLS) を有効にすることができます。
1つのコンポーネントを変更すると、他のコンポーネントに影響を与える可能性があります。例えば：
- アクティブなプロファイルにまだ割り当てられている証明書は削除できません。
- 通知がアクティブなサブスクリプションに紐づいている場合、通知は削除できません。リクエストの結果はエラーとなります。
この階層を理解することで、構成エラーや予期しない動作を回避できます。
次の例は、サブスクリプション、通知プロファイルと認証設定の間の階層に基づいて削除ルールがどのように機能するかを示しています。コンポーネントを削除できるのは、そのコンポーネントが現在別のコンポーネントに紐づいていない場合のみです。
SMSサブスクリプションをフルにセットアップした例：
- 1 サブスクリプション
- 1 通知プロファイル
- 1 認証設定
通知プロファイルはアクティブなサブスクリプションに紐づいているため、削除できません。
認証設定は通知プロファイルに紐づいているため、削除できません。
サブスクリプション全体を削除できます。通知プロファイルと認証設定は残りますが、削除されたSMSサブスクリプションにはもう紐づいていません。
この段階では、認証設定は通知プロファイルに紐づいているため、削除できません。
これで、通知プロファイルを削除できます。認証設定はそのまま残ります。
認証設定を削除できるようになりました。
メッセージ送信リクエストに含めるウェブフックURLの設定
ウェブフックのURLは、"NotifyURL" や "TrackingURL" などのフィールドを使って、メッセージ送信リクエスト内で直接定義できます。これにより、サブスクリプションを構成せずに基本的なイベント通知をすばやく受信できます。
但し、メッセージリクエスト内でウェブフックURLを設定すると、そのメッセージに対して構成されたサブスクリプションは 上書きされます。
このアプローチは、サブスクリプションを設定せずに通知を受信するための迅速なソリューションとなります。これは、きめ細かな制御が不要なフォールバックを行う必要が出た時や高速テストを実施するシナリオがある場合に最適です。
サブスクリプションを使用する計画がある場合、メッセージリクエスト内にURLを設定するのは避けるようにしてください。ウェブフックURLがメッセージペイロードで指定されている場合、構成されているすべてのサブスクリプションロジックが上書きされます。
次の例は、メッセージリクエスト内にウェブフックURLを直接設定した場合と、Webインターフェイス または サブスクリプションAPI を通じて構成した場合の違いを示しています。この例では、リクエスト内で定義されたウェブフックURLを持つメッセージは、サブスクリプションが存在する場合でも、サブスクリプションを完全にバイパスします。
