データのクエリ

メトリクスAPIは、サービス全体のトラフィックに関連するクエリと結果の抽出を容易にします。このAPIをシステムにシームレスに統合しておくと、事業活動の様々な側面に関するインサイトを得られるようになります。

分析用の非同期クエリ

クエリの送信

クエリを送信するには、メトリクスAPIにPOSTリクエストを出す必要があります。APIは、このリクエストをバックグラウンドで処理するように NTT CPaaS に指示します。クエリの送信が成功すると、APIは201ステータス、ならびに後の手順でクエリを参照する時に必要になる requestIDを返します。

{
  "callbackUrl": "{https://example.com/receive}",
  "request": {
    "filterBy": {
      "accountKeys": [
        "{AccountKeys}"
      ],
      "sentSince": "2024-04-01T00:00:00.000+0000",
      "sentUntil": "2024-04-01T01:00:00.000+0000",
      "includeSubaccounts": true,
      "directions": [
        "OUTBOUND"
      ],
      "channelCodes": [
        "SMS"
      ]
    },
    "aggregateBy": [
      "ACCOUNT_KEY",
      "HOUR",
      "DIRECTION",
      "STATUS"
    ],
    "metrics": [
      "TOTAL_TRAFFIC_COUNT",
      "DELIVERED_TRAFFIC_COUNT"
    ]
  }
}

リクエストに (callbackUrl パラメーターを使って) コールバックURLパラメーターを指定して、処理されたクエリ結果の出力先を決めておくと、ワークフローの効率性を高められます。

クエリの処理状況の取得

クエリの処理状況を確認したい時は、メトリクスAPIに GETリクエストを送信します。その際、POSTコールで返されたリクエストIDを指定する必要があります。

curl -L -g 'https://{baseUrl}/metrics/1/requests/{requestId}' \
-H 'Authorization: {authorization}' \
-H 'Accept: application/json'

リクエスト本文

このセクションでは、クエリのJSONリクエスト本文で使用できる各パラメーターについて説明します。クエリで使用できるメトリクスとディメンションの詳細については、メトリクスとフィルター と題したセクションをご参照ください。

制約

レガシーアカウント

メトリクスAPIは、従来のアカウント設定では使用できない場合があります。この機能へのアクセスに問題がある場合は、サポート (opens in a new tab)にお問い合わせください。

時間範囲のクエリ

メトリクスAPIを使用すると、様々な時間粒度で集計データを取得できます。使用可能な粒度と要求された日数の範囲によって生じる制約については、以下の通りです：

許容粒度：

• HOUR (時間)
• DAY (日)
• WEEK_SUNDAY (週_日曜日)
• WEEK_MONDAY (週_月曜日)
• WEEK_SATURDAY (週_土曜日)
• MONTH (月)
• QUARTER (四半期)
• YEAR (年)

リクエストされた日数の範囲によっては、使用できない粒度があります。制約の概要を以下に示します：