Reports API

通信APIを使用すると、サーバーログと通話明細レコード（CDR）の2種類のレコードが作成されます。Reports APIを使用すると、CDRをダウンロードできます。発信元と着信先の電話番号、ステータス、期間などの属性に基づいてCDRをフィルタリングできます。サポートされているパラメータのリストを参照.メッセージ本文/テキストを含むことができ、任意のSubaccountのレポートをダウンロードすることができます。

Reports APIは、以下のような様々なユースケースで使用することができます：

顧客への請求 - すべてのサブアカウントに関連するトランザクションをダウンロードし、含まれている価格データを使用して顧客への請求額を決定します。
請求書の照合 - 利用データと受け取った請求書を比較します。
モニタリングと分析 - リアルタイムのCDRデータをビジネスインテリジェンスや分析システムに追加し、他のイベントと関連付けます。
キャンペーン管理 - セルフサービスツールでキャンペーンのパフォーマンスを監視します。
デバッグ - 最大13ヶ月分の詳細な使用データを調査することで、問題のトラブルシューティングを行います。
不正行為の防止 - 不正行為を特定し、パターンを監視して、不正行為を行うユーザーをブロックする。詐欺ディフェンダー製品である。

幅広いフィルターを使ってCDRを照会できます。データレコードは13ヶ月間（最大保存期間）またはVideo APIの場合は90日間保存されます。13ヶ月（Video APIの場合は90日）より古いレコードはシステムから自動的に削除されるため、取得することはできません。

同期運転と非同期運転

クエリのパターンに応じて、Reports APIの2つのアプローチのいずれかを選択できます：

同期
非同期

について同期バージョンは、データレコードの小バッチの頻繁かつ定期的な検索に最適化されています。典型的なバッチサイズは、1クエリあたり1レコードから数万レコードです。

について 非同期 バージョンは、頻度の少ない大規模なデータクエリ用に最適化されている。典型的なバッチサイズは数千から数百万レコードです。

特集概要

以下の表は、Reports APIを使用する同期方法と非同期方法の機能を比較したものです：

特徴	レポート同期（GETエンドポイント）	レポート非同期（POSTエンドポイント）
データ検索	最大1000レコードのバッチで結果を即座に返す。レスポンスには、データレコードのバッチと次のバッチへのリンク（もしあれば）が含まれます。	すぐにデータを返さない。その代わりに、データ要求を記録し、非同期に処理し、すべてのレコードを含むファイルを作成する。結果ファイルの準備ができると、そのファイルへのリンクを返します。
出力フォーマット	JSON	CSV
圧縮	Applications	CSVファイルはダウンロードを高速化するために圧縮されています。
レポートTTL	Applications	レポートファイルは72時間後に自動的に削除されます。
時間フィルター	1回のクエリで最大13カ月（Video APIは90日間）のデータを取得可能。	1回のクエリで最大13カ月（Video APIは90日間）のデータを取得可能。
IDフィルター	IDで1つのデータレコードをフェッチできる	IDフィルタリングに対応していない
メッセージ本文	メッセージ本文の取得が可能	メッセージ本文の取得が可能
Subaccounts	Subaccountごとに個別の申請が必要	1つのレポート要求が必要です。Subaccountに属するデータレコードを自動的に1つのレポートにまとめます。
コールバック	Applications	HTTP(S)POSTコールバックを生成して、レポートが完了したことを通知することができます。

パフォーマンスについて:Reports APIは高速で膨大な量のデータを扱うことができますが、リアルタイム分析のためにデータをダウンロードしようとすると遅くなることがあります。賢明なフィルターを使用することで、処理を大幅にスピードアップすることができます。

対応製品

SMS API
Messages API:
- SMS/MMS
- RCS
- WhatsApp
- バイバー
- インスタグラム
- メッセンジャー
Voice API:
- シップ
- PSTN
- ウェブRTC
- 海難救助
- TTS
- AMD
Video API
Conversation API
ベリファイAPI
Numbersインサイト
Reports API
ネットワークAPI（製品名NETWORK_API-EVENT）：
- SIMスワップAPI
- アイデンティティ・インサイトAPI

価格

価格については、こちらをご覧ください。このページ.以下の例に含まれる価格値は、説明のためのものである。

価格設定例`GET` リクエスト)

直近1分間のSMSレコードを検索し、この時間帯に300件のレコードがあることが判明したとします。このレポートの合計料金は次のようになります：

Charge = 300 * 0.0004€ = 0.12€

GET リクエスト（JSONレポートの作成と取得）は、ID別または所属期間別にレコードを返すことができます。IDによる検索は、時間に縛られません。期間検索は24時間までの範囲をサポートします。

価格設定例`POST` リクエスト)

1日分のデータを取得するためにSMSレポートを作成し、このレポートに10,000件のCDRが含まれているとすると、このレポートの合計料金は以下のようになります：

Charge = 10,000 * 0.0004€ = 4€

Reports API の使用状況を確認する方法は？

製品 "REPORTS-USAGE "について、同期的にレコードをロードするか、非同期的にレポートを作成することで、Reports APIの使用状況を確認できます。

注：この機能は追加料金なしでご利用いただけます。

同期的にレコードを取得する

この情報を取得するには、HTTP GETリクエストを使用する：

curl --location --request GET 'https://api.nexmo.com/v2/reports/records?account_id=<API-KEY>&product=REPORTS-USAGE&date_start=YYYY-MM-DDTHH:MM:SSZ&date_end=YYYY-MM-DDTHH:MM:SSZ' --header 'Authorization: Basic <basic auth hash>='

以下のような返信が届きます。その "items_count": 3 は、検索期間中に3件のレポートが抽出されたことを示す。

{
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/records?account_id=<API-KEY>&product=REPORTS-USAGE&date_start=YYYY-MM-DDTHH%3AMM%3ASSZ&date_end=YYYY-MM-DDTHH%3AMM%3ASSZ"
    }
  },
  "request_id": "555042c5-368a-4fd2-b983-f24197692bac",
  "request_status": "SUCCESS",
  "received_at": "2021-10-07T09:08:58+00:00",
  "price": 0.0,
  "currency": "",
  "limit": 1000,
  "items_count": 3,
  "include_subaccounts": false,
  "records": [
    ...
  ],
  "product": "REPORTS-USAGE",
  "account_id": "<API-KEY>",
  "date_start": "2021-10-06T00:00:00+00:00",
  "date_end": "2021-10-07T23:59:00+00:00",
  "endpoint_type": "PUBLIC"
}

非同期にレコードを取得する

レコードを非同期に取得するには、非同期レポートを作成して product 値を "REPORTS-USAGE "に設定する。次の例は、非同期レポートの作成方法を示している：

curl -X POST https://api.nexmo.com/v2/reports/ \ -u $API_KEY:$API_SECRET \ -H "Content-Type: application/json" \ -d '{"account_id": "API_KEY","product": "REPORTS-USAGE","direction": "outbound","date_start": "2024-06-01T00:00:00+0000","date_end": "2024-07-01T00:00:00+0000"}'

詳細はコマンドラインを使ってCSVレポートを作成するページを参照されたい。

コード・スニペット

チュートリアル

APIリファレンス

Reports API リファレンス