メトリック API ガイド

Metrics API は、Analyze ダッシュボードに表示されるのと同じ集計パフォーマンスデータへのプログラムによるアクセスを提供します。すべてのコミュニケーションチャネルにわたる配信率、クリック率、トラフィック数、その他のチャネルパフォーマンス指標をクエリします。

メトリック API は、次の必要がある場合に使用します。

パフォーマンスデータを独自のダッシュボードまたはレポートシステムに統合します
カスタム時間の粒度化 (時間、日、週、月、四半期、年) を使用したメトリックのクエリ
チャネル全体のパフォーマンスレポートを自動化
ダッシュボードがエクスポートする以外のエンゲージメントおよび配信データへのアクセス

機能	メトリック API	課金使用状況 API	Analyze ダッシュボード
データタイプ	パフォーマンス(配信、エンゲージメント)	財務 (コスト)	パフォーマンス
アクセス	非同期 API	非同期 API	Webインターフェイス
時間の粒状化	時間から年間へ	日、月	時間から年(同じ制約が適用されます)
保持	クエリごとに最大 366 日	当月 + 2 か月前	1年間
マルチテナント	アプリケーション、エンティティ	アプリケーション、エンティティ	アプリケーション、エンティティ

重要要求ごとの最大クエリ範囲は、14日(毎時)、93日(日次)、366日(週次、月次、四半期次、年次)の粒度によって異なります。詳細は時間粒度制約を参照してください。

アクセスと可用性

Metrics API を使用するには、metrics:manageスコープの APIキーが必要です。APIキーのスコープを設定するには、API authorizationを参照してください。

デフォルトでは、結果にはアカウントのデータのみが含まれます。関連するサブアカウントを含めるには、includeSubaccountsをtrueに設定します。サブアカウントでログインすると、自分のアカウントデータのみが表示されます。

重要メトリクス API は、従来のアカウント設定では使用できません。これはアーキテクチャ上の制限であり、要求に応じて有効にすることはできません。アカウントで従来の設定が使用されているかどうか不明な場合は、アカウントマネージャーにお問い合わせください。

カバレッジ

メトリック API は、次のチャネルをサポートしています。

メモモバイルプッシュ通知、番号検索、 Live Chat、および電子メール検証は、Metrics API では利用できません。

仕組み

メトリック API は、非同期の要求/応答パターンを使用します。

要求を送信する
メトリック、フィルター、集計ディメンションを使用して Metrics API エンドポイントに POST します。

要求 ID を受け取る
API は、要求 ID (HTTP 201) をすぐに返します。処理は非同期に実行されます。

結果を得る

Callback (only way to receive results): callbackUrl is required in every request. Results are pushed to your endpoint when processing completes.
Polling (status only): Use the request ID to check whether processing has finished or failed. This endpoint returns requestId, status, and failureMessage. It does not return the result data.

完全な要求と応答のスキーマについては、 Metrics API リファレンスを参照してください。

リクエストを作成する

すべてのリクエストには、callbackUrl と request オブジェクトが含まれている必要があります。request 内では、metrics と aggregateBy の両方が必要であり、filterBy は channelCodes、sentSince、および sentUntil を指定する必要があります。他のすべてのフィルターはオプションです。リクエストとレスポンスの完全な例については、「集計されたトラフィックデータのクエリ」を参照してください。

メトリクス [#metrics]

計算する 1 つ以上のメトリック・コードを指定します。指標はチャネル固有です。

メッセージングチャネル(SMS、MMS、WhatsApp、Viberビジネスメッセージ、RCS、Facebook Messenger、Telegram、LINEなどのOTT（Over The Top）チャネル):メッセージングメトリックリファレンスを参照してください。
電子メール: 電子メールメトリックリファレンスを参照してください。
Voice and Video: Voice and Video metrics referenceを参照してください。

フィルタ [#filters]

フィルターを使用して、含めるデータを絞り込みます。チャネルと時間範囲が必要です。他のすべてのフィルターはオプションです。

フィルター	説明
時間範囲	`sentSince` と `sentUntil` (必須、ISO 8601 UTC)。time granulation constraintsを参照してください。
チャンネル	`channelCodes` (必須)。`SMS`、`EMAIL`、`WHATSAPP`などのチャネルコード。完全なリストについては、チャネルコードを参照してください。
国	`countryIds` は、数値の国 ID のリストです。これは、ISO 3166-1 alpha-2 コードを使用する Billing Usage API とは異なります。
差し出し人	送信者 ID、番号、またはドメイン
送信者の種類	すべての値については、送信者タイプを参照してください。
インタラクションタイプ	メッセージコンテンツの形式。チャネル別(RCS、カカオ)。すべての値については、インタラクションタイプを参照してください。
機能	チャネル内のサービスまたはテクノロジーのバリエーション(`VIBER_BM`や`VIBER_BOTS`など)。すべての値については、Capabilities を参照してください。
方向	'アウトバウンド', 'インバウンド'
トラフィックの種類	チャネル固有の値。完全なリストについては、「集計されたトラフィックデータのクエリ」を参照してください。これらのコードは、Billing Usage APIで使用されるトラフィックタイプコードとは異なります。
ステータスグループ	「保留中」、「配信不能」、「配信済み」、「期限切れ」、「拒否済み」
エラーグループ/コード	特定のエラーカテゴリ
キャンペーン/コミュニケーションID	キャンペーン識別子
キャンペーン参照	外部参照 ID
アプリケーション/エンティティ	マルチテナント識別子
アカウントキー	階層内の特定のアカウント
サブアカウントを含む	`true`に設定すると、指定したアカウントと一緒にサブアカウントからのトラフィックデータが含まれます。デフォルトは `false` です。
エンゲージメント期間	タイムバケットを使用してイベント間の経過時間でフィルタします: `timeToDeliver` (配信時間)、`timeToAnswer` (通話に応答するまでの時間)、`timeToClickFromSeen` (表示後のクリック)、 `timeToClickFromDelivered` (配信後のクリック)、 `timeToSeenFromDelivered` (配信後に表示)、 `timeToOpenFromDelivered` (配信後に開く)。`from`バケットは包括的で、`to`バケットは排他的です。

チャネルコード [#channel-codes]

これらのコードは、channelCodesフィルタとCHANNEL_CODEでグループ化された結果で使用します。

コード	チャネル
`SMS`	SMS
`MMS`	MMSです
「メール」	メール
「ワッツアップ」	WhatsApp
`RCS`	RCS
「バイバー」	Viber(Viberビジネスメッセージ、Viberボット)
`VOICE_VIDEO`	VoiceとVideo
`APPLE_MB`	Apple Messages for Business
「フェイスブック」	Facebook Messenger
「テレグラム」	Telegram
「インスタグラム」	Instagram(Instagramダイレクトメッセージ)
「カカオ」	カカオ(カカオアリムトーク、カカオブランドメッセージ、カカオサンダム)
「ライン」	LINE(LINE公式アカウント、LINE公式お知らせ)
「ザロ」	Zalo (Zalo Notification Services、Zalo フォロワー)

複数のサービス(Viber、Kakao、LINE、Zalo)を使用するチャネルの場合、Capabilitiesフィルターを使用してサービスバリアントを区別します。

集計基準 [#aggregate-by]

aggregateBy を使用して、結果を 1 つ以上のディメンションでグループ化します。少なくとも 1 つのディメンションが必要です。

メモURLを非 URL 指標と組み合わせることはできません。たとえば、UNIQUE_URL_CLICK_COUNT は aggregateBy: URL では有効ですが、TOTAL_TRAFFIC_COUNT は有効ではありません。

グループ	寸法
時間	`HOUR`, `DAY`, `WEEK_SATURDAY_START`, `WEEK_SUNDAY_START`, `WEEK_MONDAY_START`, `MONTH`, `QUARTER`, `YEAR`
アカウント	`ACCOUNT_KEY`、`ACCOUNT_NAME`
チャンネル	`CHANNEL_CODE`, `CHANNEL_NAME`, '方向', `TRAFFIC_TYPE`, '能力', `INTERACTION_TYPE`
地理	`COUNTRY_ID`, `COUNTRY_NAME`, `COUNTRY_CODE`, `NETWORK_ID`, `NETWORK_NAME`
差し出し人	'送信者', `SENDER_TYPE`, `SENDER_DOMAIN`
キャンペーン	「コミュニケーション」、`CAMPAIGN_REFERENCE`
マルチテナント	`APPLICATION_ID`、`ENTITY_ID`
地位	`STATUS_GROUP`, 'ステータス', `ERROR_GROUP`, `ERROR_CODE`
エンゲージメント	`TIME_TO_DELIVER`、`TIME_TO_CLICK_FROM_SEEN`、`TIME_TO_CLICK_FROM_DELIVERED`、`TIME_TO_SEEN_FROM_DELIVERED`、`TIME_TO_OPEN_FROM_DELIVERED`
エンゲージメント (Voice のみ)	`TIME_TO_ANSWER`
その他	`URL`、`RECIPIENT_DOMAIN`

メモCHANNEL_CODE は、aggregateBy で指定されているかどうかに関係なく、常に結果に含まれます。これにより、メートル法の精度が保証されます。CHANNEL_CODE も CHANNEL_NAME も指定されていない場合は、CHANNEL_CODE が暗黙的に追加されます。CHANNEL_NAMEで集計した場合、CHANNEL_CODEは自動的に追加されません。両方の値が必要な場合は、両方を明示的に指定します。

時間粒度の制約 [#time-granulation-constraints]

最大時間範囲は、選択した造粒によって異なります。

造粒	最大時間範囲	例文
`時`	14日間	2024-05-01 から 2024-05-14: `HOUR` を使用する
`日`	93日間	2024-02-01 から 2024-05-05: `DAY` を使用する
`WEEK_SATURDAY_START`, `WEEK_SUNDAY_START`, `WEEK_MONDAY_START`, '月', '四半期', '年'	366日間	2023-06-01 から 2024-05-27: 週単位、`MONTH`、`QUARTER`、または `YEAR` の粒度を使用

応答データ

結果はJSONとしてコールバックURLに配信されます。ポーリングでは、処理状況のみが返され、結果データは返されません。コールバックペイロードには、次の最上位フィールドが含まれています。

フィールド	説明
`requestId`	クエリ要求の一意の識別子
'ステータス'	要求が成功したか (`SUCCESS`)、または失敗したか
`response.requestedPeriod`	クエリで使用される時間範囲 (`sentSince` と `sentUntil`)
`response.totalRows`	返されるデータ行の合計数
'応答.列'	結果の各列を記述する配列: `columnName` (メトリックまたはディメンションコード) と `columnDataType` (`STRING`, `INTEGER`, `NUMBER`, `BOOLEAN`, `DATE_TIME`)
`response.rows`	データ行の配列。各行には、`columns` 配列と同じ順序の値が含まれています。`N/A`は、メトリックがそのチャネルまたは行の組み合わせに適用されないことを示します。

要求の状態を確認すると、より小さなペイロード requestId、status、および failureMessage が返され、状態が FAILED の場合の原因が説明されます。

完全なレスポンススキーマと例については、「集計されたトラフィックデータのクエリ」を参照してください。

パフォーマンスに関する考慮事項

時間の粒度化を複数のグループ化ディメンションと組み合わせる場合:

時間ごとの造粒: グループ化寸法は 1 から 2 に制限されます。時間単位のデータを多くのディメンション(国 + ネットワーク + 送信者)と組み合わせると、処理が大幅に遅くなる可能性があります。
日と月の粒度化: 広範な分析のために複数の次元を適切に処理します。
大規模なアカウント階層: クエリは、デフォルトでメインアカウントのデータのみを返します。サブアカウントを含めるには、includeSubaccounts: trueを設定します。accountKeysを使用して、結果を階層内の特定のアカウントに制限します。

よくある質問

同じ期間に送信された Total トラフィックが Total よりも多いのはなぜですか?

SMS トラフィックの合計が SMS メッセージの合計と異なるのはなぜですか?

Metrics API と Billing Usage API が異なる合計を返すのはなぜですか?

トラブルシューティング

問題点	ソリューション
コールバックURLが結果を受信していない	コールバック URL がパブリックにアクセス可能であることを確認します。受信要求をブロックする可能性のあるファイアウォール規則を確認します。最初の応答で返された要求 ID を確認して、要求が受け入れられたことを確認します。
401 不正エラー	APIキーに`metrics:manage`スコープがあることを確認します。「 API 認証を参照してください。
検証エラー	`callbackUrl` が存在すること、`filterBy` に `channelCodes`、`sentSince`、`sentUntil` が含まれていること、および少なくとも 1 つのメトリックと 1 つの `aggregateBy` ディメンションが指定されていることを確認します。時間範囲が選択した造粒の制限を超えていないことを確認してください。
メトリック API にアクセスできません	APIキーに`metrics:manage`スコープがあることを確認します。スコープが正しい場合、アカウントはレガシ設定を使用できますが、これは要求に応じて有効にできないアーキテクチャ上の制限です。アカウントマネージャーに問い合わせて確認してください。
レート制限エラー	レート制限の詳細と再試行のガイダンスについては、 Metrics API リファレンスを参照してください。

関連ページ

Analyzeダッシュボード
コードを必要とせずに、Web インターフェイスで同じパフォーマンスデータを探索できます。

メッセージング指標リファレンス
メッセージングチャネルのメトリック定義、API構文、およびチャネルサポートマトリックス。

メールメトリクスリファレンス
メール固有の配信、エンゲージメント、フィードバックの指標。

課金利用API
請求書に合わせたコストデータをプログラムでクエリし、財務調整を行います。