Identity Insights API を使い始める

このガイドでは、Vonage Identity Insights API を使用するために必要なすべての手順を説明します。

前提条件

始める前に、以下のものが必要です：

Vonageのアカウント：登録はこちらからまだ持っていないなら
cURL:APIコールを行うために使用します。インストールは cURLダウンロードページお好きなパッケージマネージャーを使ってください。

Identity Insights API は、複数の地域のエンドポイントから利用できる。本ガイドの例では EU エンドポイントを使用していますが、全リストは以下を参照してください。技術詳細.

環境を整える

Identity Insightsの一部は、ネットワーク機能に依存している。このような場合、2 つの異なる環境が存在する：

製造.この環境は、いくつかの国でサポートされている通信事業者からのライブデータを返します。本番環境へのアクセスには、携帯電話会社の承認が必要です。アクセスを要求する方法については、以下の手順に従ってください。本ガイド.
遊び場.プレイグラウンドは、APIコールが許可された電話番号の小さなグループに対してのみライブデータを返す、安全で制御されたテスト環境です。本番環境とは異なり、オペレーターからの承認は必要ありません。さらに、プレイグラウンドではバーチャル・オペレーター偽の、しかし決定論的な応答を生成するシミュレートされた演算子。

このガイドでは、2つの重要な理由から、仮想オペレーターとともにプレイグラウンド環境を使用します：

オペレーターの承認を必要とせず、すぐにAPIを使用することができる。
世界中のどこからでもAPIをテストすることができる。

新規アプリケーションの作成

始めるには、新しいアプリケーションを作成する必要がある。このアプリケーションには、APIコールに必要な認証情報が含まれる。以下の手順に従ってください：

に行く。ダッシュボードをクリックし、左側のメニューから「アプリケーション」を選択します。
新規アプリケーションの作成」ボタンをクリックします。
Name "フィールドにアプリケーションの名前を入力します。
公開鍵と秘密鍵を生成」をクリックして鍵ペアを生成します。秘密鍵ファイルが自動的にダウンロードされます。このファイルはJWTの生成に必要なので、安全に保存してください。
機能セクションまでスクロールし、「Playground」環境の「Network Registry」機能を有効にする。QOD」や「Verify (SA)」などの機能は、Identity Insights では使用しないため、ここで有効にする必要はない。
Generate new application "ボタンをクリックして、作成プロセスを終了します。
生番号でテストしたい場合は、その番号を許可リストあなたの遊び場で。

アプリケーションが作成されたら、ダッシュボードに表示されるアプリケーションIDをコピーします。このApplication IDは、秘密鍵ファイルを生成する際に必要となります。 JWT API リクエストの認証に使用します。

最初のAPIコールを行う

ダッシュボードの使用

よりスタートアップUI をダッシュボードに表示することで、コードを書くことなくAPIを使用することができ、認証生成や接続に関する摩擦をなくすことができます。2つのテストモードがあります：

サンドボックス 事前に定義された電話番号のリストから選択し、モック例を使ってAPIの動作を調べます。
ライブだ： お好みのアプリケーションを選択し、サポートされている機能に基づいて電話番号をテストします。

A screenshot showing the Getting Started UI for the Identity Insights API in the Vonage customer dashboard.

cURLの使用

コンパクトで自己完結的なJSONトークンであるJWTを使用して自分自身を認証します。JWTを生成するには、私たちのオンラインジェネレーターあるいは Vonage CLI.

JWTを取得したら、APIにリクエストを送信できます。以下の例では、提供された電話番号を検証する Format Insight API への cURL リクエストを示しています。 447009000000)、その番号のフォーマットに基づいて追加情報を取得する：

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
   "phone_number": "447009000000",
   "insights": {
      "format": {}
    }
  }'

以下の回答例は次のことを示している。 is_format_valid として戻ってきた。 true - これには、さまざまなレベルで番号の長さとプレフィックスの詳細を検証し、正確性とグローバルな番号標準への準拠を確認することが含まれます。有効な形式とは、その番号が通信事業者からユーザーに合法的に割り当てられることを意味するが、その番号が現在通信事業者に割り当てられていることや、到達可能であることを保証するものではない。

また、提供された電話番号のカントリー・プレフィックス、2文字および3文字の国コード、国際電話番号のフォーマットなどの情報も返されます。 E.164 フォーマットと、電話番号が属する国の地域慣習があります。それぞれのフィールドについては API仕様.

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "format": {
         "country_code_iso2": "GB",
         "country_code_iso3": "GBR",
         "country_name": "United Kingdom",
         "country_prefix": "44",
         "offline_location": "Texas",
         "time_zones": [
            "America/Chicago"
         ],
         "number_international": "447920000000",
         "number_national": "07920 000000",
         "is_format_valid": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      }
   }
}

SIMスワップなど、ネットワークレジストリを使用するインサイトを使用する場合は、以下のように purpose パラメータを指定します。提供される値は、アプリケーションに関連付けられたネットワークプロファイルの目的の 1 つと一致する必要があります。以下の例では、SIM Swap インサイトを使用して、提供された電話番号に関連する最近の SIM ペアリングの変更をチェックしています、 447009000000:

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
   "phone_number": "447009000000",
   "purpose": "FraudPreventionAndDetection",  
   "insights": {
      "sim_swap": {
         "period": 240
      }
    }
  }'

この応答例では is_swapped パラメータは true日付と時刻（UTC）。 ISO 8601 フォーマットで、最新のSIMスワップがいつ実行されたかを示す：

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "sim_swap": {
         "latest_sim_swap_at": "2024-07-08T09:30:27.504Z",
         "is_swapped": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      }
   }
}

たとえば、このリクエストは Format と SIM Swap の両方のインサイトを返します：

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
   "phone_number": "447009000000",
   "purpose": "FraudPreventionAndDetection",  
   "insights": {
      "format": {},
      "sim_swap": {
         "period": 240
      }
    }
  }'

レスポンスには、両方のインサイトリクエストの結果が含まれる：

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "format": {
         "country_code_iso2": "GB",
         "country_code_iso3": "GBR",
         "country_name": "United Kingdom",
         "country_prefix": "44",
         "offline_location": "Texas",
         "time_zones": [
            "America/Chicago"
         ],
         "number_international": "447920000000",
         "number_national": "07920 000000",
         "is_format_valid": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      },
      "sim_swap": {
         "latest_sim_swap_at": "2024-07-08T09:30:27.504Z",
         "is_swapped": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      }
   }
}

さらに読む

Identity Insights API の詳細については、以下を参照してください。 APIリファレンス.
ご不明な点がございましたら、下記までお問い合わせください。 VonageコミュニティSlack.