Erste Schritte mit der Identity Insights API

Dieser Leitfaden führt Sie durch alle notwendigen Schritte, um die Vonage Identity Insights API in Betrieb zu nehmen.

Voraussetzungen

Bevor Sie beginnen, benötigen Sie Folgendes:

  • Ein Vonage Account: Hier anmelden wenn Sie nicht bereits eine haben.
  • cURL: Damit werden Sie API-Aufrufe tätigen. Sie können es von der Seite cURL-Download-Seite mit Ihrem bevorzugten Paketmanager.

Die Identity Insights API ist über mehrere regionale Endpunkte verfügbar. Die Beispiele in diesem Leitfaden verwenden den EU-Endpunkt, aber Sie finden die vollständige Liste unter Technische Details.

Einrichten der Umgebung

Einige der Identity Insights basieren auf Netzwerkfunktionen. In solchen Fällen gibt es zwei verschiedene Umgebungen:

  • Produktion. Diese Umgebung liefert in einigen Ländern Live-Daten von den unterstützten Betreibern. Der Zugang zur Produktionsumgebung erfordert die Genehmigung der Mobilfunkbetreiber. Um zu erfahren, wie Sie den Zugang beantragen können, folgen Sie dieser Leitfaden.
  • Spielplatz. Der Playground ist eine sichere und kontrollierte Testumgebung, in der API-Aufrufe nur für eine kleine Gruppe von zugelassenen Telefonnummern Live-Daten liefern. Im Gegensatz zur Produktion ist hier keine Genehmigung der Betreiber erforderlich. Außerdem bietet der Playground Zugriff auf die Virtueller Operatorein simulierter Operator, der gefälschte, aber deterministische Antworten erzeugt.

In diesem Leitfaden werden wir die Spielplatzumgebung mit dem virtuellen Operator aus zwei wichtigen Gründen verwenden:

  • Sie ermöglicht die sofortige Nutzung der APIs, ohne dass eine Genehmigung der Betreiber erforderlich ist.
  • Es ermöglicht das Testen der APIs von jedem Ort der Welt aus.

Erstellen einer neuen Applikation

Um zu beginnen, müssen wir eine neue Anwendung erstellen. Diese Anwendung wird die Anmeldeinformationen enthalten, die für API-Aufrufe erforderlich sind. Folgen Sie diesen Schritten:

  • Gehen Sie zum Dashboard und wählen Sie "Applications" aus dem Menü auf der linken Seite.
  • Klicken Sie auf die Schaltfläche "Eine neue Anwendung erstellen".
  • Geben Sie einen Namen für Ihre Anwendung in das Feld "Name" ein.
  • Klicken Sie auf "Öffentlichen und privaten Schlüssel generieren", um ein Schlüsselpaar zu erzeugen. Es wird automatisch eine Datei mit einem privaten Schlüssel heruntergeladen. Speichern Sie diese Datei sicher, da sie für die Erzeugung von JWTs erforderlich ist.
  • Blättern Sie zum Abschnitt "Fähigkeiten" und aktivieren Sie die Fähigkeit "Netzwerkregistrierung" für die "Playground"-Umgebung. Funktionen wie "QOD" oder "Verify (SA)" müssen hier nicht aktiviert werden, da sie von Identity Insights nicht verwendet werden.
  • Klicken Sie auf die Schaltfläche "Neuen Antrag generieren", um den Erstellungsprozess abzuschließen.
  • Wenn Sie mit echten Numbers testen möchten, fügen Sie diese zu den Erlaubnisliste auf deinem Spielplatz.

Nachdem die Anwendung erstellt wurde, kopieren Sie die auf dem Dashboard angezeigte Anwendungs-ID. Sie benötigen diese Application ID zusammen mit der privaten Schlüsseldatei, um die JWTs zur Authentifizierung von API-Anfragen.

Machen Sie Ihren ersten API-Aufruf

Verwendung des Dashboards

Von der Erste Schritte UI im Dashboard können Sie die API auch nutzen, ohne Code zu schreiben, so dass keine Reibungsverluste im Zusammenhang mit der Authentifizierungserstellung oder der Konnektivität entstehen. Es bietet zwei Testmodi:

  • Sandkasten: Wählen Sie aus einer vordefinierten Liste von Telefonnummern, um das API-Verhalten anhand von nachgebildeten Beispielen zu untersuchen.
  • Live: Wählen Sie die von Ihnen bevorzugte Anwendung aus und testen Sie Telefonnummern auf der Grundlage der von ihr unterstützten Funktionen.
A screenshot showing the Getting Started UI for the Identity Insights API in the Vonage customer dashboard.

cURL verwenden

Authentifizieren Sie sich mit einem JWT, einem kompakten und in sich geschlossenen JSON-Token. Um ein JWT zu erzeugen, können Sie unser Online-Generatoroder verwenden Sie alternativ die Vonage CLI.

Sobald Sie Ihr JWT haben, können Sie eine Anfrage an die API senden. Das folgende Beispiel zeigt eine cURL-Anfrage an die API für das Format insight, mit der die angegebene Telefonnummer validiert wird (in diesem Fall 447009000000), und rufen Sie zusätzliche Informationen auf der Grundlage des Formats dieser Nummer ab:

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

Die folgende Beispielantwort zeigt, dass is_format_valid ist zurückgekehrt als true - Dabei werden die Länge und die Details der Vorwahl auf verschiedenen Ebenen überprüft, um die Genauigkeit und die Übereinstimmung mit den globalen Nummerierungsstandards sicherzustellen. Ein gültiges Format bedeutet, dass die Nummer von den Netzbetreibern rechtmäßig an die Nutzer vergeben werden kann. Es ist jedoch keine Garantie dafür, dass die Nummer derzeit einem Netzbetreiber zugewiesen oder erreichbar ist.

Außerdem werden Informationen wie die Ländervorwahl, zwei- und dreistellige Ländercodes für die angegebene Telefonnummer sowie die Nummer in Übereinstimmung mit den internationalen E.164 Format und die lokalen Konventionen des Landes, zu dem die Telefonnummer gehört. Weitere Informationen zu den einzelnen Feldern finden Sie in der API-Spezifikation.

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

Wenn Sie Einblicke verwenden möchten, die die Netzwerkregistrierung nutzen, wie z. B. SIM Swap, müssen Sie die purpose Parameter in Ihrer Anfrage. Der angegebene Wert muss mit einem der Netzprofilzwecke übereinstimmen, die mit Ihrer Anwendung verbunden sind. Im folgenden Beispiel wird der SIM-Swap-Einblick verwendet, um zu prüfen, ob die SIM-Kopplung für die angegebene Telefonnummer kürzlich geändert wurde, 447009000000:

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

In dieser Beispielantwort wird die is_swapped Parameter wurde zurückgegeben als truezusammen mit einem Datum und einer Uhrzeit in UTC ISO 8601 Format, um anzuzeigen, wann der letzte SIM-Tausch stattgefunden hat:

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

Sie können eine beliebige Kombination von Erkenntnissen in einem einzigen API-Aufruf verwenden. So gibt diese Anfrage beispielsweise sowohl die Erkenntnisse über Format als auch über SIM-Tausch zurück:

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

Die Antwort enthält dann die Ergebnisse der beiden Einsichtsanträge:

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

Weitere Lektüre