Verwendung der Reports API mit Laravel

Einführung

Die Vonage Reports API bietet leistungsstarke, filterbare Nutzungsanalysen. Dieses Tutorial zeigt, wie man sie in Laravel integriert, um synchrone und asynchrone Berichte zu erstellen. Wenn Sie also z. B. die Voice API oder Messages API intensiv nutzen, können Sie Statistiken von Ihrem Vonage API Dashboard abrufen. Dabei gibt es jedoch Einschränkungen, da Sie nur die Datensätze der letzten 30 Tage abrufen können. Alternativ können Sie die Reports API verwenden, die API-Endpunkte für eine tiefere Analyse Ihrer Nutzung, das Hinzufügen spezifischer Parameter zum Filtern von Daten oder die asynchrone Erstellung größerer Berichte öffnet. Anstelle von 30 Tagen können Sie die Datensätze der letzten 13 Monate abrufen, oder die letzten 90 Tage, wenn Sie Videodaten abfragen. Wenn Sie die Reports API nutzen möchten, wird Ihnen die Anzahl der Datensätze, die in den Berichten zurückgegeben werden, entsprechend in Rechnung gestellt.

Nachdem Sie diese Aufschlüsselung gelesen haben, sind Sie vielleicht schon ein Vielnutzer von Vonage, der eine maßgeschneiderte Preisgestaltung benötigt: In diesem Fall empfehlen wir Ihnen, sich an Ihren Account Manager zu wenden, um einen Unlimited Plan zu erhalten. Unsere allgemeine Empfehlung bei der Wahl der Preise ist, zum Unlimited Plan zu wechseln, wenn Sie mehr als 1 Million Ereignisse pro Monat oder 12 Millionen Datensätze pro Jahr abrufen.

In diesem Artikel werden wir Laravel verwenden, um diese Daten als Beispiel abzurufen.

Voraussetzungen

• Komponist

• PHP8.2+

• Laravel-Installateur

• ngrok

• Ein Vonage API-Konto

Vonage API-Konto

Um dieses Tutorial durchzuführen, benötigen Sie ein Vonage API-Konto. Wenn Sie noch keines haben, können Sie sich noch heute anmelden und mit einem kostenlosen Guthaben beginnen. Sobald Sie ein Konto haben, finden Sie Ihren API-Schlüssel und Ihr API-Geheimnis oben auf dem Vonage-API-Dashboard.

Sind Sie bereit, mit dem Bau zu beginnen?

Erleben Sie nahtlose Konnektivität, Echtzeit-Messaging und kristallklare Sprach- und Videoanrufe - alles auf Knopfdruck.

Installation von Laravel

Der Laravel-Installer umgeht den Mechanismus von Composer create-project Mechanismus zur Erstellung von Boilerplate-Code. Erstellen Sie ein neues Verzeichnis auf Ihrem Entwicklungsrechner und führen Sie laravel install reports-api-demo. Das Installationsprogramm bietet Ihnen eine Reihe von Optionen - Sie können die Standardoptionen auswählen und die Option Laravel Starter Kits überspringen, da wir nur demonstrieren wollen, wie wir mit Daten umgehen.

Einrichten von Routen

Um die Dinge so einfach wie möglich zu halten, werden wir drei Routen einrichten, die den drei verschiedenen Möglichkeiten entsprechen, wie Sie Berichte implementieren können. Diese Routen werden die folgenden sein:

• Treffen Sie einen GET Endpunkt, der einen synchronen Bericht der zu Ihrer Anwendung zurückkehrt, und diese spuckt das Ergebnis aus

• Treffen Sie einen GET Endpunkt, der eine POST Anfrage an Vonage für einen asynchronen Bericht auslöst, mit einer Callback-URL, die

• A POST Endpunkt, an den Vonage mit Ihrem asynchronen Bericht antwortet

Route eins: Erstellen eines synchronen Berichts

Navigieren Sie zu Ihrem routes/web.php Verzeichnis und fügen Sie den folgenden Code ein:

Route::get('/report', function () {
    $apiKey = '99913011';
    $apiSecret = 's09IJad98fa0t9j09ad8fa999';
    $url = 'https://api.nexmo.com/v2/reports/records';
    $dateStart = \Carbon\Carbon::now()->subMonth();
    $dateEnd = \Carbon\Carbon::now();

    $queryParams = [
       'product' => 'SMS',
       'direction' => 'outbound',
       'date_start' => $dateStart->format('Y-m-d\TH:i:s.vP'),
       'date_end' => $endDate->format('Y-m-d\TH:i:s.vP'),
       'account_id' => $apiKey,
     ];

    $response = Http::withBasicAuth($apiKey, $apiSecret)
       ->get($url, $queryParams);

    dd($response->json());
});

(Für die Schlauen unter Ihnen: Ja, das sind Dummy-API-Schlüssel; verbergen Sie immer Ihre sensiblen Daten!). Um eine bessere Vorstellung davon zu bekommen, wie Sie Ihre Umgebungsvariablen handhaben können sehen Sie sich diesen Blog-Artikel an.

Anstatt Controller zu verwenden, fügen wir die Logik in den Routenabschluss ein. Durch Drücken von /report in Ihrer Anwendung wird nun eine Anfrage an die Reports API unter Verwendung Ihres Schlüssels und Geheimnisses (Sie finden diese in Ihrem Dashboard) ausgelöst und die Antwort wird ausgegeben.

In dieser Anfrage wird der Bericht nur Ereignisse aus der SMS API zurückgeben, da wir in den Abfrageparametern nach diesem Produkt gefiltert haben. In dieser API gibt es viele Optionen für die Abfrage:

• SMS

• Voice (einschließlich IN-APP-VOICE, WEBSOCKET-CALL, VOICE-TTS, ASR, AMD)

• Messages API (WhatsApp, RCS, SMS, Viber, SMS)

• Nummer Einsicht

• Verify

• In-App Messaging

• Netzwerk-APIs

• Video

Dies ist für kleine Datenmengen geeignet, aber was passiert, wenn Sie Millionen von Zeilen benötigen? Hier kommt der asynchrone Bericht ins Spiel.

Route zwei: Asynchrone Berichte erstellen

Millionen von Datensätzen wären sowohl für den Client als auch für den Server eine zu große Belastung. Daher können Sie POST eine Anfrage mit Berichtsabfrageparametern im JSON-Körper mit einer Callback-URL, an die nach Abschluss ein Webhook übergeben wird. Da Vonage einen Endpunkt benötigt, an den die Berichtsdaten gesendet werden, müssen Sie Ihre Anwendung dem Internet aussetzen. Am schnellsten geht dies mit ngrok, das genau dies tut. Sobald Sie ngrok installiertführen Sie es aus, um Ihre Anwendung freizugeben, und notieren Sie sich die URL.

Wir brauchen einen Endpunkt, um den Bericht zu empfangen. Zu Demonstrationszwecken werden die Daten zunächst nur in die Anwendungsprotokolldatei ausgegeben.

Route::post('/incoming', function (\Illuminate\Http\Request $request) {
   \Illuminate\Support\Facades\Log::info($request->json());
});

Als nächstes benötigen wir eine neue GET Endpunkt, um die asynchrone Anfrage zu starten:

Route::get('/async', function (\Illuminate\Http\Request $request) {
   $apiKey = '99913011';
   $apiSecret = 's09IJad98fa0t9j09ad8fa999';
   $url = 'https://api.nexmo.com/v2/reports';
   $dateStart = Carbon::now()->subMonth();
   $endDate = Carbon::now();

   $queryParams = [
       'product' => 'SMS',
       'direction' => 'outbound',
       'date_start' => $dateStart->format('Y-m-d\TH:i:s.vP'),
       'date_end' => $endDate->format('Y-m-d\TH:i:s.vP'),
       'account_id' => $apiKey,
   ];



   $response = Http::withBasicAuth($apiKey, $apiSecret)
       ->post($url, $queryParams);

   dd($response->json());
});

Ersetzen Sie Ihren API-Schlüssel und Ihr Geheimnis wieder durch Ihr Live Dashboard Anmeldeinformationen und ersetzen Sie das Feld callback_url Feld mit Ihrer ngrok-URL, plus /async hinzugefügt, um Vonage zu POST an den richtigen Ort zu bringen. Rufen Sie diese GET Anfrage in Ihrem Browser auf, und der Bericht wird ausgelöst. Es ist wichtig zu beachten, dass die Datensätze zeilenweise kostenpflichtig sind es sei denn, Sie haben einen verwalteten Account, Vergewissern Sie sich also beim Testen dieser Implementierung, dass Sie nicht vorhaben, die Server mit Millionen von Datensätzen zu belasten, wenn Sie diese haben und dies nur zu Testzwecken tun.

Sie werden schließlich (je nach Größe des Berichts) in der Lage sein, zu navigieren storage/logs/laravel.log und die Daten des asynchronen Berichts sehen.

Anzeigen des Status eines asynchronen Berichts

Vielleicht möchten Sie überprüfen, ob Sie einen Rückruf verpasst haben, z. B. wenn ein Parsing-Fehler auftrat, der dazu führte, dass der Bericht an eine ungültige URL gesendet wurde. Sie möchten sowohl den Status anzeigen als auch den Bericht herunterladen, wenn er abgeschlossen ist. Dies können Sie tun, indem Sie den Endpunkt Bericht prüfen anklicken.

Route::get('/status', function (\Illuminate\Http\Request $request) {
   $apiKey = 'your-api-key';
   $apiSecret = 'your-api-secret';
   $requestId = 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab';
   $url = 'https://api.nexmo.com/v2/reports/' . $requestId;

   $response = Http::withBasicAuth($apiKey, $apiSecret)
       ->get($url);

   dd($response->json());
});

Die Antwort gibt Ihnen alle nötigen Informationen. Vorausgesetzt, dass die request_status ist. SUCCESSist, können Sie den Download-Link aus dem download_report HAL-Feld entnehmen.

"request_status": "SUCCESS",
"_links": {
    "self": {
         "href": "https://api.nexmo.com/v2/reports/aaaaaaaa-bbbb-cccc-dddd-  0123456789ab"
          },
          "download_report": {
              "href": "https://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
           }
       }
}

Schlussfolgerung

Und schon haben Sie eine vollständig asynchrone Möglichkeit, Ihre gesamte Cloud Platform-Kommunikation abzufragen! Die Möglichkeit der Abfrage nach Account-ID bietet Ihnen zusätzliche Optionen: Wenn Sie der Hauptnutzer sind, dann verwenden Sie Ihren API-Schlüssel. In diesem Fall haben Sie jetzt die Möglichkeit, benutzerdefinierte Berichte pro Sub-Account zu erstellen. Dies ist auch besonders nützlich, um als Wiederverkäufer Rechnungen an Kunden auszustellen. Sie können die Reports API auch verwenden, um Ihre eigenen Muster potenziell bösartiger Anfragen zu überwachen und zu identifizieren und Numbers zu sperren, indem Sie der Fraud Defender-Funktionalität.