https://d226lax1qjow5r.cloudfront.net/blog/blogposts/introducing-the-vonage-reports-api/Blog_Vonage-Reports-API_1200x600.png

Vonage Reports API のご紹介

最終更新日 April 19, 2021
#nodejs
#python
#reports-api

所要時間：1 分

注 この記事は、Reports APIがベータ版であったときに公開されました。 ベータ版. 我々は Reports API が一般公開されました、これにより、Voice、Messaging、Verify、Identity Insights、Video のすべてのレポートにアクセスできるようになります。一般提供開始のお知らせを見るにはここをクリックしてください： Vonage Reports APIが一般公開されました。

Vonage Reports API Vonage Reports APIは、アカウント全体で行われるすべてのアクティビティに関するデータを収集できる堅牢なAPIです。

この投稿では、どのようなデータがエクスポートできるのか、JavaScriptとPythonの両方でどのようにアクセスできるのか、そしてこのようなAPIを使うことで何が理解できるのかを見ていこう。

レポートAPIの概要

Reports APIは、他のAPIの使用によって生成されるすべての基礎データへのアクセスを提供するAPIです。例えば、アカウントからSMSを送信すると、そのアクションが記録されます：

  • メッセージの送信料

  • 配送状況

  • 受取人がいる国

  • 受信者のネットワーク・プロバイダー

  • メッセージ本文

  • メッセージの配信にかかった時間

そして、それはほんの一部に過ぎない！非常に詳細なAPIで、生成されるレポートに含まれる情報の量を完全にコントロールすることができます。

どの製品のレポートを入手できますか？

Reports APIは以下をカバーします。 SMS, Voice, Verify, ナンバーインサイト, メッセージ, 会話および自動音声認識の使用。

さらに、インバウンドまたはアウトバウンドの使用状況をレポートに表示することもできます。

Reports API によるデータの要求

Reports APIで行うことができるリクエストには2種類あります：

  • 同期：最大約10,000レコードまでの小バッチのデータを頻繁に定期的に検索するために最適化されています。

  • 非同期：数千万レコードを返す、頻繁でない大規模なクエリに最適化されています。

同期と非同期

どの方法を使うかを決める1つの方法は、データを収集したい頻度を見ることだ。

もし、データの最新表示やオンデマンド表示が必要で、1時間ごとや毎日リクエストするのであれば、同期リクエスト方式が適切だろう。

あるいは、データ収集の頻度はそれほど高くないが、1ヶ月の使用で大量のレコードが生成されることがわかっているとする。その場合は、非同期リクエストメソッドがよい選択です。

平均して、非同期リクエスト・メソッドは、100万レコードを生成して返すのに約5-10分かかる。

同期レポートを入手する

まず、Node.jsとPythonの標準ライブラリを使って、24時間にわたるSMSデータの同期リクエストから始めます。これらのリクエストには特別なものは必要ないので、お好みのHTTPライブラリを使うようにアレンジしてください。

Node.js 同期リクエスト

Node.jsを使って最大24時間分のデータをリクエスト：

#!/usr/bin/env node

const https = require('https');
const querystring = require('querystring');

const VONAGE_API_KEY = 'YOUR_VONAGE_API_KEY';
const VONAGE_API_SECRET = 'YOUR_VONAGE_API_SECRET';

const reportsAPIParams = {
  account_id: VONAGE_API_KEY,
  product: 'SMS',
  direction: 'outbound',
  date_start: '2020-01-01T00:00:00Z',
  date_end: '2020-01-01T23:59:59Z',
};

const options = {
  hostname: 'api.nexmo.com',
  path: '/v2/reports/records?' + querystring.stringify(reportsAPIParams),
  method: 'GET',
  auth: `${VONAGE_API_KEY}:${VONAGE_API_SECRET}`,
};

const requestReport = https.request(options, (res) => {
  res.on('data', (data) => {
    console.log(JSON.parse(data));
  });
});

requestReport.on('error', (e) => {
  console.error(e);
});

requestReport.end();

Python 同期リクエスト

Pythonを使って最大24時間分のデータをリクエスト：

#!/usr/bin/python

import requests
import base64

from requests.auth import HTTPBasicAuth

VONAGE_API_KEY = "YOUR_VONAGE_API_KEY"
VONAGE_API_SECRET = "YOUR_VONAGE_API_SECRET"

payload = {
    "account_id": VONAGE_API_KEY,
    "product": "SMS",
    "direction": "outbound",
    "date_start": "2020-01-01T00:00:00Z",
    "date_end": "2020-01-01T00:00:00Z",
}

r = requests.get('https://api.nexmo.com/v2/reports/records',
                 params=payload, auth=HTTPBasicAuth(VONAGE_API_KEY, VONAGE_API_SECRET))

print(r.json())

非同期レポートデータのリクエスト

次に、SMSのデータに対して同じリクエストを行うが、今回は最大1,000万件のレコードを返すことを期待している。 1000万レコードそのため、この部分は非同期リクエスト・メソッドに切り替えます。この処理の流れは次のようになる：

  • 非同期レポート・データの要求を行う。 callback_urlを与える。そして request_id応答で受け取った

  • (オプション)リクエストされたレポートのステータスを確認するには request_id.ステータスが SUCCESSが表示されます。 download_urlが表示されます。 _linksセクションに表示されます。

  • でHTTPリクエストを受け取る。 callback_url.これにはセクション _linksセクションが含まれています。 download_urlを持つセクションが含まれます。

  • 報告書のダウンロードは download_url.

Node.js 非同期リクエスト

Node.jsを使用して、非同期レポートの生成要求を行う：

#!/usr/bin/env node

const https = require('https');

const VONAGE_API_KEY = 'YOUR_VONAGE_API_KEY';
const VONAGE_API_SECRET = 'YOUR_VONAGE_API_SECRET';

const reportsAPIParams = JSON.stringify({
  account_id: VONAGE_API_KEY,
  product: 'SMS',
  direction: 'outbound',
  callback_url: 'https://myapplication.biz/reports/receive',
});

const options = {
  hostname: 'api.nexmo.com',
  path: '/v2/reports',
  method: 'POST',
  auth: `${VONAGE_API_KEY}:${VONAGE_API_SECRET}`,
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': reportsAPIParams.length,
  },
};

const req = https.request(options, (res) => {
  res.on('data', (data) => {
    console.log(JSON.parse(data));
  });
});

req.on('error', (e) => {
  console.error(e);
});

req.write(reportsAPIParams)
req.end();

Python 非同期リクエスト

Pythonを使用して、非同期レポート生成のリクエストを行う：

#!/usr/bin/python

import requests
import json
import base64

from requests.auth import HTTPBasicAuth

VONAGE_API_KEY = "YOUR_VONAGE_API_KEY"
VONAGE_API_SECRET = "YOUR_VONAGE_API_SECRET"

payload = {
    "account_id": VONAGE_API_KEY,
    "product": "SMS",
    "direction": "outbound",
    "date_start": "2020-01-01T00:00:00Z",
    "date_end": "2020-01-02T00:00:00Z",
    "callback_url": "https://myapplication.biz/reports/receive"
}

r = requests.post('https://api.nexmo.com/v2/reports',
                  json=payload, auth=HTTPBasicAuth(VONAGE_API_KEY, VONAGE_API_SECRET))

print(r.json())

レポートのステータスの確認

レポートのステータスはいつでも確認することができます。 PENDING状態なのかを確認することができます。

Node.jsでレポートのステータスをチェックする

Node.jsでasychronousレポートのステータス更新を取得する：

#!/usr/bin/env node

const https = require('https');

const VONAGE_API_KEY = 'YOUR_VONAGE_API_KEY';
const VONAGE_API_SECRET = 'YOUR_VONAGE_API_SECRET';

const REQUEST_ID = 'REQUEST_ID_FROM_PREVIOUS_STEP';

const options = {
  hostname: 'api.nexmo.com',
  path: '/v2/reports/' + REQUEST_ID,
  method: 'GET',
  auth: `${VONAGE_API_KEY}:${VONAGE_API_SECRET}`,
};

const requestReport = https.request(options, (res) => {
  res.on('data', (data) => {
    console.log(JSON.parse(data));
  });
});

requestReport.on('error', (e) => {
  console.error(e);
});

requestReport.end();

Pythonでレポートのステータスをチェックする

Node.jsで非同期レポートのステータス更新を取得します：

#!/usr/bin/python

import requests
import base64

from requests.auth import HTTPBasicAuth

VONAGE_API_KEY = "YOUR_VONAGE_API_KEY"
VONAGE_API_SECRET = "YOUR_VONAGE_API_SECRET"

REQUEST_ID = 'REQUEST_ID_FROM_PREVIOUS_STEP';

r = requests.get('https://api.nexmo.com/v2/reports/' + REQUEST_ID,
                 auth=HTTPBasicAuth(VONAGE_API_KEY, VONAGE_API_SECRET))

print(r.json())

上記のどちらの例でも、レスポンスは次のようになる：

{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "SMS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    },
    "download_report": {
      "href": "https://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  },
  "items_count": 1,
  "direction": "outbound",
  "status": "delivered",
  "client_ref": "abc123",
  "account_ref": "abc123",
  "include_message": "true",
  "network": "23415",
  "from": "441234567890",
  "to": "441234567890"
}

レスポンスで指定された download_reportURLに注意してください。このURLは、レポートのダウンロード可能なバージョン（CSVを含むZIPファイル）へのリンクです。ファイルがサーバーから削除されるまで、72時間以内にダウンロードしてください。

レポート・ファイルをダウンロードするには認証が必要です。 開発者ポータルに例があります。

レポートAPIの優れた利用方法

Reports APIは、お客様のAccount（およびサブAccount！）のアクティビティに関して弊社から得られる最大量の情報を提供します。これは、APIがビッグデータタイプのアプリケーションに適していることを意味します：

  • Tableauなどのツールによるデータの可視化と分析。

  • データウェアハウスのデータパイプライン実装に携わる。

  • 大規模なトラフィックの傾向、問題、または不正なコストの急上昇を発見する。

  • サブアカウントを通じて）顧客の活動に関する詳細な分析を提供する。

  • アウトバウンドキャンペーンのテストと管理（特にSMSまたはMessages APIを使用）。

いったんこのデータにアクセスできれば、それを使ってできることにほとんど制限はない。

さらに読む

この紹介記事で興味をそそられたなら、次に行くべきは 完全なドキュメントをご覧ください。 Reports APIの概要を参照してください。生成されたレポートに何が含まれるかについて、より詳細な情報があります。

シェア:

https://a.storyblok.com/f/270183/250x250/d0444194cd/martyn.png
Martyn Daviesヴォネージの卒業生

元Vonage開発者教育ディレクター。クリエイティブ・デベロッパー、プロダクト・マネージャー、ハック・デイ・オーガナイザーの経歴を持つマーティンは、放送局や大手レコード会社での勤務を経て、2012年よりテクノロジー・アドボケイトとして活動している。世界中の開発者を教育し、力を与えている。