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