Numbers Einblicke - Leitfaden für den Übergang

Da die Vonage Number Insight API hat sich weiterentwickelt und seine Fähigkeiten zur Ermittlung von Telefonnummern wurden in den neueren Identitätseinblicke APISie bietet mehr Flexibilität, kombinierte Einblicke in einer einzigen Anfrage und moderne Unterstützung für Echtzeit-Carrier-Daten und Betrugspräventionsfunktionen.

Als Teil dieser Konsolidierung, die Number Insights API wird im Februar 2027 auslaufen. Nach diesem Datum wird Number Insights nicht mehr weiterentwickelt. Um Serviceunterbrechungen zu vermeiden und von einheitlichen Einblicken, neuen Netzwerkfunktionen wie SIM-Swap und Subscriber Match sowie laufenden Verbesserungen zu profitieren, wird Kunden dringend empfohlen, ihre bestehenden Number Insights-Integrationen vor diesem Stichtag auf Identity Insights zu migrieren.

Dieser Leitfaden unterstützt Sie bei der Migration Ihrer bestehenden Implementierungen, die diese Number Insights-Dienste verwenden, auf die entsprechenden Identity Insights-Anfragen:

• Numbers Einblicke Basic
• Number Insights Standard
• Numbers Einblicke Erweitert

Gemeinsame Concepts

Die folgende Tabelle zeigt, wie die bisherigen Numbers Insights Endpunkte/Attribute mit Identity Insights übereinstimmen:

Diese werden im Folgenden näher erläutert.

Format der Telefonnummern

In Numbers Insights, der Grundlegend Der Endpunkt bietet formatierte Darstellungen von Telefonnummern (national und international) und eine grundlegende Validierung.

In Identity Insights wird dies unterstützt durch das Format Einsicht, Rückgabe von Zahlenformatierung und Validierungsdetails innerhalb eines strukturierten Modells.

Original-Träger

Erbe Standard und Fortgeschrittene Number Insights liefert ein original_carrier Objekt mit Betreiberangaben, die das Netz widerspiegeln, dem die Nummer ursprünglich zugewiesen wurde.

Identity Insights unterhält diese Fähigkeit unter seiner Original-Träger Einsicht mit ähnlichen Feldern wie Name, Land, Netzwerktyp und Kennungen.

Stromträger

Numbers Insights zeigte eine current_carrier Objekt, das den Betreiber angibt, mit dem eine Mobilfunknummer derzeit verbunden ist (einschließlich Nummernübertragbarkeit, sofern unterstützt).

Identity Insights fährt fort mit seiner Stromträger Einblick, der die Live-Zuweisung für mobile Numbers widerspiegelt.

Roaming und Erreichbarkeit

Number Insights Advanced enthielt Roaming- und Erreichbarkeitsinformationen. Diese Felder wurden von HLR (Home Location Register)-basierten Abfragen abgeleitet, einem veralteten Ansatz, der zunehmend durch Datenschutzbestimmungen und technische Beschränkungen in der Branche eingeschränkt wird, was diese Datenquelle unzuverlässig macht.

Identity Insights entfernt sich von HLR-basierten Datenquellen und stützt sich stattdessen auf Netzwerk-APIs, die durch direkte Abfrage von Mobilfunknetzen zuverlässigere und Echtzeitinformationen liefern. Allerdings sind die Verfügbarkeit und die geografische Abdeckung für diese Netzwerk-API-gestützten Einblicke derzeit begrenzt, und sie sind nur über Vonage Virtual Operator verfügbar.

In Identity Insights werden diese Funktionen durch die Einblicke in Roaming und Erreichbarkeit bereitgestellt.

Fehlerbehandlung

Wie die Fehlerbehandlung in Numbers Insights funktioniert

In den früheren Numbers Insights (Basic, Standard, Advanced) erfolgte die Fehlerbehandlung normalerweise auf Anfrageebene:

• Der HTTP-Statuscode spiegelt den Gesamterfolg oder Misserfolg der Anfrage wider.
• Wenn die Anfrage erfolgreich war (z. B. HTTP 200), wurde die Anfrage selbst als erfolgreich betrachtet und die Verarbeitung abgeschlossen, auch wenn je nach Art der Nummer, Erfassungsbereich oder Datenverfügbarkeit noch einzelne Felder fehlen können.
• Ist die Anfrage fehlgeschlagen, wurden keine Teildaten zurückgegeben.
• Fehler wurden über Top-Level-Felder mitgeteilt, z. B. status, status_messageoder HTTP-Fehlerantworten.

Dieses Modell ging von einer Alles-oder-Nichts-Ausführung aus.

Wie die Fehlerbehandlung in Identity Insights funktioniert

Identity Insights führt ein Multistatus-Antwortmodell ein.

Jeder angeforderte Einblick (zum Beispiel format, original_carrier, current_carrier) wird unabhängig verarbeitet und liefert seine eigenen Statusinformationen.

Das Ergebnis ist:

• Die HTTP-Antwort kann erfolgreich sein (z. B. HTTP 200), auch wenn eine oder mehrere Einsichten fehlgeschlagen sind.
• Einige Einblicke können gültige Daten liefern, während andere Fehler zurückgeben.
• Applications müssen den Status jedes einzelnen Einblicks überprüfen.

Einblicke in die Identität: Der API-Aufruf

Mit Identity Insights können Sie mehrere Einblicke in einer Nutzlast anfordern. Hier ist ein Beispiel, das die bisherige Number Insight API-Anfrage für Basic, Standard und Advanced ersetzt:

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": {}
    }
  }'

Antwortstruktur

Eine typische Identity Insights-Antwort enthält Attribute für jeden aktivierten Einblick. Zum Beispiel:

{
   "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"
            }
        },
   }
}

Die Felder entsprechen der Legacy-Semantik, werden aber in einer einzigen JSON-Struktur zurückgegeben, was das Parsing vereinfacht.

Zusammenfassung der Checkliste

Bei der Migration:

• Ersetzen von Altlasten Basis / Standard / Fortgeschritten Number Insights Anrufe mit einer einzelne Identitätseinblicke anrufen.
• Fügen Sie die Format Einblick in die Formatierung und Validierung von Zahlen.
• Beides einbeziehen original_carrier und current_carrier Einsichtsobjekte, um die Semantik der alten Trägerdaten zu erhalten.
• Aktualisieren Sie Ihre Autorisierung zur Verwendung von JWT.