Utiliser l'API Reports avec Laravel

Introduction

L'API Reports API de Vonage de Vonage fournit des analyses d'utilisation puissantes et filtrables. Ce tutoriel montre comment l'intégrer à Laravel pour générer des rapports synchrones et asynchrones. Ainsi, si vous utilisez beaucoup, par exemple, l'API Voice ou l'API Messages, vous pouvez obtenir des statistiques à partir de votre tableau de bord de l'API Vonage. Il y a cependant des limites à cela, car vous ne pouvez obtenir que les enregistrements des 30 derniers jours. Vous pouvez également utiliser l'API Reports, qui ouvre des points d'extrémité d'API pour approfondir votre utilisation, ajouter des paramètres spécifiques pour filtrer les données ou créer des rapports beaucoup plus importants de manière asynchrone. Au lieu de 30 jours, vous pouvez récupérer les enregistrements des 13 derniers mois, ou des 90 derniers jours si vous interrogez des données Video. Si vous souhaitez utiliser l'API Reports, vous serez facturé en fonction du nombre d'enregistrements rapportés dans les rapports.

Après avoir lu cette analyse, vous êtes peut-être déjà un gros utilisateur de Vonage qui a besoin d'une tarification sur mesure : dans ce cas, nous vous recommandons de contacter votre Account Manager pour obtenir un Plan illimité. Notre recommandation générale en matière de tarification est de passer au plan illimité si vous allez chercher plus d'un million d'événements par mois, ou 12 millions d'enregistrements par an.

Dans cet article, nous allons utiliser Laravel pour récupérer ces données à titre d'exemple.

Conditions préalables

• Compositeur

• PHP8.2+

• Installateur Laravel

• ngrok

• Un Account API de Vonage

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Installation de Laravel

Le programme d'installation de Laravel s'appuie sur le mécanisme de Composer create-project de Composer pour créer du code boilerplate. Créez un nouveau répertoire sur votre machine de développement et exécutez laravel install reports-api-demo. Le programme d'installation vous proposera quelques options - vous pouvez sélectionner les options par défaut ici, et ignorer l'option Laravel Starter Kits, car nous voulons seulement faire une démonstration de la façon dont nous gérons les données.

Mise en place des itinéraires

Pour que les choses soient aussi simples que possible, nous allons avoir trois routes qui correspondent aux trois différentes façons dont vous pouvez mettre en œuvre les rapports. Ces routes seront les suivantes :

• Atteindre un GET qui génère un rapport synchrone qui revient à votre application, et qui recrachera le résultat.

• Atteindre un GET qui envoie à Vonage une demande de rapport asynchrone POST à Vonage pour un rapport asynchrone, avec une URL de rappel qui sera

• A POST point de terminaison auquel Vonage répondra avec votre rapport asynchrone

Première solution : créer un rapport synchrone

Naviguez jusqu'à votre répertoire routes/web.php et ajoutez le code suivant :

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());
});

(Pour les plus malins d'entre vous, il s'agit bien de clés API factices ; cachez toujours vos données sensibles!). Pour avoir une meilleure idée de la façon de gérer vos variables d'environnement, consultez cet article de blog.

Plutôt que d'utiliser des contrôleurs, nous ajoutons la logique dans la fermeture de l'itinéraire. En appuyant sur /report dans votre application lancera une requête à l'API Reports en utilisant votre clé et votre secret (vous pouvez les trouver dans votre tableau de bord) et affichera la réponse.

Dans cette requête, le rapport ne nous rapportera que les événements de l'API SMS, car nous avons filtré par ce produit dans les paramètres de la requête. L'API offre de nombreuses possibilités d'interrogation :

• SMS

• Voice (y compris IN-APP-VOICE, WEBSOCKET-CALL, VOICE-TTS, ASR, AMD)

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

• Numbers Insight

• Verify

• In-App Messaging

• API de réseau

• Video

Cela convient pour de petits volumes de données, mais que se passe-t-il lorsque vous avez besoin de millions de lignes ? C'est là que le rapport asynchrone entre en jeu.

Deuxième voie : créer des rapports asynchrones

Des millions d'enregistrements représenteraient une charge trop importante pour le client et le serveur. Par conséquent, vous pouvez POST une demande avec des paramètres de requête de rapport dans le corps JSON, avec une URL de rappel pour livrer un webhook lorsqu'il est terminé. Comme Vonage aura besoin d'un point de terminaison pour envoyer les données du rapport, vous devrez exposer votre application à l'Internet. Le moyen le plus rapide de le faire est d'utiliser ngrok, qui fait exactement cela. Une fois que vous avez ngrok installéexécutez-le pour exposer votre application et notez l'URL.

Nous avons besoin d'un point de terminaison pour recevoir le rapport. Pour l'instant, à titre de démonstration, les données seront uniquement transférées dans le fichier journal de l'application.

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

Ensuite, nous avons besoin d'un nouveau GET pour lancer la requête asynchrone :

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());
});

Remplacez à nouveau votre clé API et votre secret par votre tableau de bord et remplacez le champ callback_url par votre URL ngrok, plus /async ajouté pour que Vonage envoie POST au bon endroit. Accédez à cette GET dans votre navigateur, et le rapport est déclenché. Il est important de noter que les enregistrements sont facturés à la ligne à moins que vous ne disposiez d'un compte géré, Assurez-vous donc, lorsque vous testez cette implémentation, que vous n'êtes pas sur le point de frapper les serveurs avec des millions d'enregistrements si vous en avez et que vous ne suivez que cette méthode pour les tests.

Vous pourrez éventuellement (en fonction de la taille du rapport) naviguer vers storage/logs/laravel.log et voir les données du rapport asynchrone.

Visualisation de l'état d'un rapport asynchrone

Vous voudrez peut-être vérifier que vous n'avez pas manqué un rappel - par exemple, s'il y a eu une erreur d'analyse qui a signifié que le rapport a été envoyé à une URL non valide. Vous voudrez à la fois consulter l'état et, s'il est terminé, télécharger le rapport. Vous pouvez le faire en cliquant sur le point de terminaison "vérifier le rapport".

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());
});

La réponse vous donnera toutes les informations nécessaires. A condition que le request_status est SUCCESSvous pouvez extraire le lien de téléchargement du champ download_report HAL.

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

Conclusion

Et voilà, un moyen entièrement asynchrone d'interroger toutes les communications de votre plateforme Cloud ! La possibilité d'interroger par Account ID vous offre également des options supplémentaires : si vous êtes l'utilisateur principal, alors vous utiliserez votre clé API. Cependant, il se peut que vous soyez un revendeur de communications, auquel cas, vous avez désormais la possibilité de générer des rapports personnalisés par sous-compte. Ceci est particulièrement utile pour l'émission de factures aux clients en tant que revendeur. Vous pouvez également utiliser l'API Reports pour surveiller et identifier vos propres modèles de requêtes potentiellement malveillantes et bloquer des numéros à l'aide de la la fonctionnalité Fraud Defender.