https://d226lax1qjow5r.cloudfront.net/blog/blogposts/introducing-the-vonage-reports-api/Blog_Vonage-Reports-API_1200x600.png

Présentation de l'API des Reports de Vonage

Publié le April 19, 2021
#nodejs
#python
#reports-api

Temps de lecture : 5 minutes

Note : Cet article a été publié à l'origine lorsque l'API "Rapports" était en cours de développement : Cet article a été publié à l'origine lorsque l'API Reports était en version bêta. Nous avons le plaisir d'annoncer que l Reports API est désormais disponible, vous permettant d'accéder à tous vos rapports sur Voice, Messaging, Verify, Identity Insights et Video. Cliquez ici pour voir l'annonce de disponibilité générale : L'API Reports de Vonage est maintenant disponible.

L'API Reports API de Vonage est une API robuste qui vous permet de recueillir des données sur toutes les activités qui ont lieu sur votre Account.

Dans ce billet, nous verrons quelles données peuvent être exportées, comment vous pouvez y accéder avec JavaScript et Python, et ce que l'utilisation d'une telle API vous permet de comprendre.

Aperçu de l'API Reports

L'API Reports est une API qui vous donne accès à toutes les données sous-jacentes que votre utilisation de nos autres API produit. Par exemple, lorsque vous envoyez un SMS à partir de votre Account, cette action est enregistrée, ainsi que les éléments suivants :

  • Le coût de l'envoi du message

  • L'état de la livraison

  • Le pays où se trouve le destinataire

  • Le fournisseur du réseau du bénéficiaire

  • Le corps du message lui-même

  • Durée de la transmission du message

Et ce n'est pas tout ! Il s'agit d'une API très détaillée qui vous donne un contrôle total sur la quantité d'informations incluses dans les rapports générés.

Quels sont les produits pour lesquels vous pouvez obtenir des rapports ?

L'API Reports couvre les domaines suivants SMS, Voice, Verify, Numbers Insight, Messages, Conversationset l'utilisation de la reconnaissance vocale automatique.

En outre, vous pouvez choisir d'afficher dans vos rapports l'utilisation des appels entrants ou sortants, c'est-à-dire la différence entre recevoir un appel vocal (entrant) et passer un appel vocal (sortant).

Demande de données via l'API Reports

Il existe deux types de requêtes différentes que vous pouvez effectuer avec l'API Reports :

  • Synchrone : Optimisé pour l'extraction fréquente et périodique de petits lots de données jusqu'à environ 10 000 enregistrements.

  • Asynchrone : Optimisé pour les requêtes peu fréquentes et volumineuses renvoyant des dizaines de millions d'enregistrements.

Synchrone ou asynchrone

L'une des façons de décider de la méthode à utiliser consiste à déterminer la fréquence à laquelle vous souhaitez recueillir des données.

Si vous avez besoin d'une vue actualisée ou à la demande de vos données et que vous effectuez des requêtes toutes les heures ou tous les jours, la méthode de requête synchrone est appropriée.

Par ailleurs, supposons que vous souhaitiez recueillir des données moins fréquemment, mais que vous sachiez que vous allez générer de nombreux enregistrements au cours d'un seul mois d'utilisation. Dans ce cas, la méthode de requête asynchrone est le meilleur choix.

En moyenne, la méthode de requête asynchrone prend environ 5 à 10 minutes pour générer et renvoyer 1 million d'enregistrements.

Obtenir un rapport synchrone

Nous allons commencer par faire une demande synchrone de données SMS sur 24 heures en utilisant des bibliothèques standard pour Node.js et Python. Vous n'avez besoin de rien de spécial pour ces requêtes, vous pouvez donc les adapter pour utiliser la bibliothèque HTTP de votre choix.

Requête synchrone Node.js

Demandez jusqu'à 24 heures de données à l'aide de Node.js :

#!/usr/bin/env node

const https = require('https');
const querystring = require('querystring');

const VONAGE_API_KEY = 'YOUR_VONAGE_API_KEY';
const VONAGE_API_SECRET = 'YOUR_VONAGE_API_SECRET';

const reportsAPIParams = {
  account_id: VONAGE_API_KEY,
  product: 'SMS',
  direction: 'outbound',
  date_start: '2020-01-01T00:00:00Z',
  date_end: '2020-01-01T23:59:59Z',
};

const options = {
  hostname: 'api.nexmo.com',
  path: '/v2/reports/records?' + querystring.stringify(reportsAPIParams),
  method: 'GET',
  auth: `${VONAGE_API_KEY}:${VONAGE_API_SECRET}`,
};

const requestReport = https.request(options, (res) => {
  res.on('data', (data) => {
    console.log(JSON.parse(data));
  });
});

requestReport.on('error', (e) => {
  console.error(e);
});

requestReport.end();

Requête synchrone Python

Demander jusqu'à 24 heures de données en utilisant Python :

#!/usr/bin/python

import requests
import base64

from requests.auth import HTTPBasicAuth

VONAGE_API_KEY = "YOUR_VONAGE_API_KEY"
VONAGE_API_SECRET = "YOUR_VONAGE_API_SECRET"

payload = {
    "account_id": VONAGE_API_KEY,
    "product": "SMS",
    "direction": "outbound",
    "date_start": "2020-01-01T00:00:00Z",
    "date_end": "2020-01-01T00:00:00Z",
}

r = requests.get('https://api.nexmo.com/v2/reports/records',
                 params=payload, auth=HTTPBasicAuth(VONAGE_API_KEY, VONAGE_API_SECRET))

print(r.json())

Demande de données de rapport asynchrones

Ensuite, nous ferons la même demande de données sur les SMS, mais cette fois-ci, nous nous attendons à ce que le système renvoie jusqu'à 10 millions d'enregistrementsNous passerons donc à la méthode de requête asynchrone pour cette partie. Ce processus fonctionne de la manière suivante :

  • Demande de données d'état asynchrones, en fournissant un callback_url pour la notification de la disponibilité du rapport. Notez ensuite les request_id reçu dans la réponse.

  • (optionnel) Vérifier le statut du rapport demandé, en utilisant la fonction request_id. Une fois terminé, un rapport ayant le statut SUCCESS aura également le rapport download_url dans la section _links section.

  • Recevoir une requête HTTP à l'adresse callback_url. Ceci contient la section _links qui contient le download_url pour le rapport.

  • Télécharger le rapport à partir du site download_url.

Requête asynchrone Node.js

Demander la génération d'un rapport asynchrone à l'aide de Node.js :

#!/usr/bin/env node

const https = require('https');

const VONAGE_API_KEY = 'YOUR_VONAGE_API_KEY';
const VONAGE_API_SECRET = 'YOUR_VONAGE_API_SECRET';

const reportsAPIParams = JSON.stringify({
  account_id: VONAGE_API_KEY,
  product: 'SMS',
  direction: 'outbound',
  callback_url: 'https://myapplication.biz/reports/receive',
});

const options = {
  hostname: 'api.nexmo.com',
  path: '/v2/reports',
  method: 'POST',
  auth: `${VONAGE_API_KEY}:${VONAGE_API_SECRET}`,
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': reportsAPIParams.length,
  },
};

const req = https.request(options, (res) => {
  res.on('data', (data) => {
    console.log(JSON.parse(data));
  });
});

req.on('error', (e) => {
  console.error(e);
});

req.write(reportsAPIParams)
req.end();

Requête asynchrone Python

Demander la génération d'un rapport asynchrone en utilisant Python :

#!/usr/bin/python

import requests
import json
import base64

from requests.auth import HTTPBasicAuth

VONAGE_API_KEY = "YOUR_VONAGE_API_KEY"
VONAGE_API_SECRET = "YOUR_VONAGE_API_SECRET"

payload = {
    "account_id": VONAGE_API_KEY,
    "product": "SMS",
    "direction": "outbound",
    "date_start": "2020-01-01T00:00:00Z",
    "date_end": "2020-01-02T00:00:00Z",
    "callback_url": "https://myapplication.biz/reports/receive"
}

r = requests.post('https://api.nexmo.com/v2/reports',
                  json=payload, auth=HTTPBasicAuth(VONAGE_API_KEY, VONAGE_API_SECRET))

print(r.json())

Vérifier l'état de vos déclarations

Vous pouvez à tout moment vérifier l'état de vos rapports pour savoir s'ils sont terminés (auquel cas le téléchargement sera disponible) ou s'ils sont encore à l'état d'ébauche. PENDING état.

Vérifier l'état d'un rapport avec Node.js

Obtenir une mise à jour de l'état d'un rapport asychrone avec Node.js :

#!/usr/bin/env node

const https = require('https');

const VONAGE_API_KEY = 'YOUR_VONAGE_API_KEY';
const VONAGE_API_SECRET = 'YOUR_VONAGE_API_SECRET';

const REQUEST_ID = 'REQUEST_ID_FROM_PREVIOUS_STEP';

const options = {
  hostname: 'api.nexmo.com',
  path: '/v2/reports/' + REQUEST_ID,
  method: 'GET',
  auth: `${VONAGE_API_KEY}:${VONAGE_API_SECRET}`,
};

const requestReport = https.request(options, (res) => {
  res.on('data', (data) => {
    console.log(JSON.parse(data));
  });
});

requestReport.on('error', (e) => {
  console.error(e);
});

requestReport.end();

Vérifier l'état d'un rapport avec Python

Obtenir une mise à jour de l'état d'un rapport asynchrone avec Node.js :

#!/usr/bin/python

import requests
import base64

from requests.auth import HTTPBasicAuth

VONAGE_API_KEY = "YOUR_VONAGE_API_KEY"
VONAGE_API_SECRET = "YOUR_VONAGE_API_SECRET"

REQUEST_ID = 'REQUEST_ID_FROM_PREVIOUS_STEP';

r = requests.get('https://api.nexmo.com/v2/reports/' + REQUEST_ID,
                 auth=HTTPBasicAuth(VONAGE_API_KEY, VONAGE_API_SECRET))

print(r.json())

Pour les deux exemples ci-dessus, la réponse ressemblera à ceci :

{
  "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "request_status": "SUCCESS",
  "product": "SMS",
  "account_id": "abcdef01",
  "date_start": "2017-12-01T00:00:00+00:00",
  "date_end": "2018-01-01T00:00:00+00:00",
  "include_subaccounts": "false",
  "callback_url": "https://requestb.in/12345",
  "receive_time": "2019-06-28T15:30:00+0000",
  "start_time": "2019-06-28T15:30:00+0000",
  "_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"
    }
  },
  "items_count": 1,
  "direction": "outbound",
  "status": "delivered",
  "client_ref": "abc123",
  "account_ref": "abc123",
  "include_message": "true",
  "network": "23415",
  "from": "441234567890",
  "to": "441234567890"
}

Notez l'URL download_report spécifiée dans la réponse. Cette URL est un lien vers la version téléchargeable du rapport (un fichier ZIP contenant un fichier CSV). Vous avez jusqu'à 72 heures pour télécharger le fichier avant qu'il ne soit supprimé de nos serveurs, et vous devrez réexécuter votre requête de rapport pour le régénérer.

Des informations d'identification sont nécessaires pour télécharger le fichier de rapport. un exemple sur le portail des développeurs montre comment procéder.

De bonnes façons d'utiliser Reports API

L'API Reports vous donne la plus grande quantité d'informations que vous pouvez obtenir de notre part concernant l'activité de vos comptes (et sous-comptes !). Cela signifie que l'API se prête à des applications de type big data, telles que :

  • Visualisation et analyse des données à l'aide d'outils tels que Tableau.

  • Participer à la mise en œuvre d'un pipeline de données pour les entrepôts de données.

  • Repérer les tendances du trafic, les problèmes ou les pics de coûts frauduleux à grande échelle.

  • Fournir aux clients des analyses approfondies sur leur activité (via des sous-comptes).

  • Tester et gérer des campagnes sortantes (notamment avec les API SMS ou Messages).

Une fois que vous avez accès à ces données, il y a très peu de limites à ce que vous pouvez en faire.

Pour en savoir plus

Si ce billet d'introduction a suscité votre intérêt, vous devriez ensuite consulter la documentation complète pour l'API Reports ainsi que la vue d'ensemble de l'API Reports où vous trouverez encore plus de détails sur le contenu d'un rapport généré.

Partager:

https://a.storyblok.com/f/270183/250x250/d0444194cd/martyn.png
Martyn DaviesAnciens de Vonage

Ancien directeur de la formation des développeurs chez Vonage. Avec une expérience de développeur créatif, de gestionnaire de produits et d'organisateur de journées de hacking, Martyn travaille comme défenseur de la technologie depuis 2012, après avoir travaillé dans le secteur de la radiodiffusion et dans de grandes maisons de disques. Il forme et responsabilise les développeurs du monde entier.