Numbers Insight Advanced API

2027年2月4日をもって、VonageはVonage Number Insightsを終了いたします。継続的なサポートを確保し、よりスケーラブルで将来性のあるソリューションを提供するため、当社の強化されたソリューションへの移行をお勧めします： Vonage Identity Insights API.Vonage Identity Insight APIは、複数の電話番号関連データセットを1つの柔軟なAPIに統合し、電話番号に関するリアルタイムの情報を要求したり、番号のフォーマット、キャリアの詳細、SIMスワップ、加入者照合などのインサイトを1回の呼び出しで自由に組み合わせて取得できるようにします。

をご確認ください。 Numbersインサイト移行ガイドAPIの相違点、必要な変更点、スムーズな移行のためのベストプラクティスに関する詳細なガイダンスを提供しています。

Number Insight APIは、世界中の電話番号に関するリアルタイム情報を提供します。3つのレベルがあります：ベーシック、スタンダード、アドバンス。

Advancedレベルでは、詐欺やスパムから組織を保護するための最も包括的なデータを提供します。BasicやStandardレベルとは異なり、通常、Advanced APIには非同期でアクセスします。 ウェブフック.

このチュートリアルでは

このチュートリアルでは、Node.jsとExpressを使用して、電話番号を受け付け、その番号が利用可能になったときにその番号に関する洞察情報を返すRESTfulなWebサービスを作成します。

そのためには、以下のステップを踏む：

  1. プロジェクトの作成 - Node.js/Expressアプリケーションを作成します。
  2. をインストールします。 vonage パッケージ - プロジェクトにVonageの機能を追加する。
  3. アプリケーションをインターネットに公開する - 使用 ngrok を使用して、VonageがWebhook経由でアプリケーションにアクセスできるようにします。
  4. 基本アプリケーションの作成 - 基本的な機能を構築する。
  5. 非同期リクエストの作成 - Number Insight Advanced APIを呼び出す。
  6. ウェブフックを作成する - 入力されたインサイトデータを処理するコードを書く。
  7. アプリケーションのテスト - それを実際に見てみよう！

前提条件

チュートリアルを完了するには

  • A Vonageアカウント - APIキーとシークレット
  • ングロク - 開発用Webサーバをインターネット経由でVonageのサーバにアクセスできるようにする。

プロジェクトの作成

アプリケーション用のディレクトリを作成します、 cd ディレクトリに移動し、Node.js パッケージ・マネージャーを使用します。 npm を作成する。 package.json ファイルでアプリケーションの依存関係を指定します：

mkdir myapp cd myapp npm init

Enter]を押して、各デフォルトを受け入れる。

次に エクスプレス ウェブアプリケーションフレームワークと ボディパーサー パッケージ：

npm install express body-parser --save

をインストールします。 vonage パッケージ

以下を実行する。 npm コマンドをターミナルウィンドウに入力してVonage Node Server SDKをインストールします：

npm install @vonage/server-sdk

アプリケーションをインターネットに公開する

Number Insight APIがリクエストの処理を完了すると、Number Insight APIはアプリケーションに次のようなアラートを送ります。 ウェブフック.Webhookは、Vonageのサーバーがあなたのサーバーと通信するためのメカニズムを提供します。

アプリケーションがVonageのサーバにアクセスできるようにするには、インターネット上で一般に公開されている必要があります。開発とテスト中にこれを実現する一つの方法は ングロクローカルサーバーを安全なトンネルを経由して公衆インターネットに公開するサービス。参照 このブログ記事 をご覧ください。

ダウンロードとインストール ングロクそして次のコマンドで起動する：

./ngrok http 5000

これは、ローカルマシンのポート5000で実行されているすべてのWebサイトのパブリックURL（HTTPおよびHTTPS）を作成します。

を使用する。 ngrok ウェブ・インターフェース http://localhost:4040 のURLをメモしておく。 ngrok このチュートリアルを完了するために必要です。

基本アプリケーションの作成

を作成する。 index.js ファイルを以下のコードで置き換えてください。 VONAGE_API_KEY, VONAGE_API_SECRET そして WEBHOOK_URL 定数を独自の値で指定する：

const app = require('express')();
const bodyParser = require('body-parser');

app.set('port', 5000));
app.use(bodyParser.json());

const VONAGE_API_KEY = // Your Vonage API key
const VONAGE_API_SECRET = // Your Vonage API secret
const WEBHOOK_URL = // e.g. https://bcac78a0.ngrok.io/webhooks/insight

app.get('/insight/:number', function(request, response) {
    console.log("Getting information for " + request.params.number);
}); 

app.listen(app.get('port'), function() {
    console.log('Listening on port', app.get('port'));
});

ターミナルで以下のコマンドを実行し、表示される結果を受け取ってテストする：

node index.js Listening on port 5000

ブラウザで以下のURLを入力し、次のように置き換えてください。 https://bcac78a0.ngrok.io ホスト名 ngrok を供給している：

https://bcac78a0.ngrok.io/insight/123456

すべてが正常に機能している場合、 Getting information for 123456 とターミナルに表示される。

非同期リクエストの作成

アプリケーションが電話番号を受信できるようになったので、Number Insight Async APIへの非同期リクエストを作成する必要がある。

のインスタンスを作成するコードを書く。 Vonage をアカウント詳細とともに送信してください：

const Vonage = require('@vonage/server-sdk');
const vonage = new Vonage({
    apiKey: VONAGE_API_KEY,
    apiSecret: VONAGE_API_SECRET
});

そして、次のようにする。 /insight/:number ルートで Number Insight API を呼び出し、対象の番号とレスポンスを処理する Webhook の URL を渡す。Webhookは後のステップで作成します。

app.get('/insight/:number', function(request, response) {
    console.log("Getting information for " + request.params.number);
    nexmo.numberInsight.get({
        level: 'advancedAsync',
        number: request.params.number,
	callback: WEBHOOK_URL
    }, function (error, result) {
	if (error) {
	    console.error(error);
	} else {
	    console.log(result);
	}
    });
});

Numbers Insight Advanced APIへの呼び出しは、実際のインサイトデータが利用可能になる前に、要求を確認する即時応答を返します。コンソールにログを記録するのは、この応答です：

{ request_id: '3e6e31a4-3efb-49ab-8751-5a43e4de6406', number: '447700900000', remaining_balance: '17.775', request_price: '0.03000000', status: 0 }

について status フィールドは、操作が成功したかどうかを示す。ゼロの値は成功を示し、ゼロ以外の値は失敗を示す。 Numbers Insight APIリファレンスドキュメント.

ウェブフックを作成する

インサイトAPIは、結果を POST リクエストを定義する必要があります。 /webhooks/insight ルートハンドラを app.post()ご覧の通りである：

app.post('/webhooks/insight', function (request, response) {
    console.dir(request.body);
    response.status(204).send();
});

ハンドラーは、入力されたJSONデータをコンソールに記録し 204 VonageのサーバーへのHTTPレスポンス。

HTTPステータスコード204は、サーバーがリクエストに成功し、レスポンスペイロードボディに送信すべき追加コンテンツがないことを示す。

アプリケーションのテスト

走る index.js:

node index.js

ブラウザのアドレスバーに以下の形式でURLを入力する。 https://bcac78a0.ngrok.io あなたの ngrok URLと INSIGHT_NUMBER をご希望の電話番号と一緒にお送りください：

http://YOUR_NGROK_HOSTNAME/insight/NUMBER

最初の確認応答の後、コンソールは以下のような情報を表示するはずである：

{ "status": 0, "status_message": "Success", "lookup_outcome": 0, "lookup_outcome_message": "Success", "request_id": "55a7ed8e-ba3f-4730-8b5e-c2e787cbb2b2", "international_format_number": "447700900000", "national_format_number": "07700 900000", "country_code": "GB", "country_code_iso3": "GBR", "country_name": "United Kingdom", "country_prefix": "44", "request_price": "0.03000000", "remaining_balance": "1.97", "current_carrier": { "network_code": "23410", "name": "Telefonica UK Limited", "country": "GB", "network_type": "mobile" }, "original_carrier": { "network_code": "23410", "name": "Telefonica UK Limited", "country": "GB", "network_type": "mobile" }, "valid_number": "valid", "reachable": "reachable", "ported": null, "roaming": "unknown" }

アプリケーションをテストする際には、以下のことを考慮してください：

  • Insight Advanced APIでは、Standard APIで利用できない固定電話に関する情報は提供されません。
  • インサイトAPIへのリクエストは無料ではありません。リクエストには ngrok ダッシュボードで開発中に以前のリクエストを再生し、不必要な課金を避ける。

結論

このチュートリアルでは、Number Insight Advanced Async APIを使用してWebhookにデータを返すアプリケーションを作成しました。

このチュートリアルでは、IPアドレスのマッチング、リーチャビリティ、ローミングステータスなど、Advanced APIに特有の機能のいくつかをカバーしていない。チュートリアルの ドキュメンテーション をご覧ください。

次はどこだ？

以下のリソースは、Numbers Insightをアプリケーションで使用する際に役立ちます：