Numbersインサイト移行ガイド

として Vonage番号 Insight API が進化し、電話番号インテリジェンスの機能は、より新しいものに統合された。アイデンティティ・インサイトAPIまた、より高い柔軟性、単一のリクエストでの統合された洞察、リアルタイムのキャリアデータと不正防止機能の最新のサポートを提供します。

この統合の一環である、 Number Insight APIは2027年2月をもって終了します。.この日付以降、Numbers Insights は廃止されます。サービスの中断を避け、統合された洞察、SIMスワップや加入者マッチなどの新しいネットワーク機能、および継続的な機能強化の恩恵を受けるために、お客様はこの期限前に既存のNumber Insights統合をIdentity Insightsに移行することを強くお勧めします。

このガイドは、Numbers Insightsサービスを使用する既存の実装を、同等のIdentity Insightsリクエストに移行する際に役立ちます：

Numbersインサイトベーシック
Numbersインサイト・スタンダード
Numbersインサイトアドバンス

共通のコンセプト

以下の表は、従来のNumber Insightsのエンドポイント/属性とIdentity Insightsの整合性を示している：

レガシー・ナンバー・インサイト	アイデンティティ・インサイト
基本： Numbersフォーマット	フォーマット
スタンダード／アドバンス `original_carrier`	キャリア独自の洞察
スタンダード／アドバンス `current_carrier`	現在のキャリアの見識

これらについては、以下でさらに詳しく説明する。

電話番号形式

ナンバーインサイトでは ベーシック エンドポイントは、電話番号（国内および国際）のフォーマットされた表現と、基本的な検証を提供した。

Identity Insights では、次のようにサポートされている。 フォーマット 構造化されたモデルの中で、番号のフォーマットと検証の詳細を返す。

オリジナル・キャリア

レガシー スタンダード そして上級インサイトが返した数字 original_carrier オブジェクトには、番号が最初に割り当てられたネットワークを反映するキャリアの詳細が含まれる。

アイデンティティ・インサイトは、この機能を オリジナル・キャリア 名前、国名、ネットワークタイプ、識別子などの類似フィールドを持つインサイト。

現在のキャリア

Numbersインサイト current_carrier オブジェクトは、携帯電話番号が現在関連付けられているキャリアを示す（サポートされている場合は番号ポータビリティを含む）。

アイデンティティ・インサイトは、引き続き 現在のキャリア 携帯電話番号のライブ割り当てを反映したインサイト。

ローミングとリーチャビリティ

Numbers Insights Advancedは、ローミング情報と到達可能性情報を公開した。これらのフィールドは、HLR（Home Location Register）ベースのルックアップから派生したものである。このレガシーなアプローチは、プライバシー規制や業界全体の技術的制限によってますます制約を受けるようになっており、このデータソースの信頼性が低くなっている。

Identity Insights は、HLR ベースのデータソースから離れ、モバイルネットワークに直接クエリを発行することで、より信頼性の高いリアルタイムの情報を提供するネットワーク API に依存する。ただし、これらのネットワーク API ベースの洞察の利用可能性と地理的範囲は現在限られており、Vonage Virtual Operator を通じてのみ公開されている。

Identity Insightsでは、これらの機能はRoamingおよびReachabilityインサイトを通じて提供される。

エラー処理

Numbersインサイトでのエラー処理の仕組み

従来のNumbers Insights（Basic、Standard、Advanced）では、エラー処理は通常リクエストレベルでした：

HTTPステータスコードは、リクエストの全体的な成否を反映していた。
リクエストが成功した場合（例えばHTTP 200）、リクエスト自体は成功したとみなされ、処理は完了した。
リクエストが失敗した場合、部分データは返されなかった。
エラーは、次のようなトップレベルのフィールドを通じて伝えられた。 status, status_messageまたはHTTPエラー・レスポンス。

このモデルでは、オール・オア・ナッシングの実行を想定していた。

Identity Insights でのエラー処理の仕組み

Identity Insights はマルチステータス応答モデルを導入している。

要求された各見識（例えば format, original_carrier, current_carrier)は独立して処理され、独自のステータス情報を返す。

その結果だ：

HTTPレスポンスは、1つ以上のインサイトが失敗しても成功することがある（HTTP 200など）。
有効なデータを返すインサイトもあれば、エラーを返すインサイトもあります。
申請は、各見識の状況を個別に検査しなければならない。

アイデンティティの洞察APIを呼び出す

Identity Insights では、1 つのペイロードで複数のインサイトをリクエストできます。以下は、Basic、Standard、Advanced リクエストに対する従来の Number Insight API リクエストを置き換えた例です：

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

注： Identity Insights の呼び出しには、JWT 認証トークンを使用する必要があります。 api_key/api_secret レガシーNumber Insight APIで使用されるスタイル。JWTの詳細については認証を案内する。

対応体制

通常の Identity Insights レスポンスには、有効化された各インサイトの属性が含まれる。例えば

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "format": {
         "country_code": "US",
         "country_name": "United States",
         "country_prefix": "1",
         "offline_location": "Georgia",
         "time_zones": [
            "America/New_York"
         ],
         "number_international": "+14040000000",
         "number_national": "(404) 000-0000",
         "is_format_valid": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      },
      "original_carrier": {
            "name": "AT&T Mobility",
            "network_type": "MOBILE",
            "country_code": "US",
            "network_code": "310090",
            "status": {
                "code": "OK",
                "message": "Success"
            }
        },
"current_carrier": {
            "name": "AT&T Mobility",
            "network_type": "MOBILE",
            "country_code": "US",
            "network_code": "310090",
            "status": {
                "code": "OK",
                "message": "Success"
            }
        },
   }
}

フィールドはレガシーのセマンティクスと一致しますが、単一のJSON構造で返されるため、解析が簡素化されます。

要約チェックリスト

移行するとき

レガシーの置き換え ベーシック／スタンダード／アドバンス Numbersのインサイトコール数 シングル・アイデンティティ コール。
を含む。 フォーマット 数値の書式設定と検証のためのインサイト。
両方を含む original_carrier そして current_carrier レガシーキャリアデータのセマンティクスを維持するためのインサイトオブジェクト。
JWTを使用するように認可を更新してください。