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

Presentamos Reports API de Vonage

Publicado el April 19, 2021
#nodejs
#python
#reports-api

Tiempo de lectura: 4 minutos

Nota: Este artículo se publicó originalmente cuando la Reports API estaba en fase Beta. Nos complace anunciar que la Reports API ya está disponible de forma general, que le da acceso a todos sus informes de Voice, Messaging, Verify, Identity Insights y Video. Haz clic aquí para ver el anuncio de disponibilidad general: Reports API de Vonage ya está disponible en general.

En API de Reports de Vonage es una API sólida que te permite recopilar datos sobre toda la actividad que tiene lugar en tu Account.

En este post, veremos qué datos se pueden exportar, cómo se puede acceder a ellos tanto con JavaScript como con Python, y qué ayuda a comprender el uso de una API como ésta.

Descripción general de Reports API

Reports API es una API que le da acceso a todos los datos subyacentes que produce el uso de nuestras otras API. Por ejemplo, cuando envías un SMS desde tu Account, esa acción queda registrada, junto con lo siguiente:

  • Coste de envío del mensaje

  • Estado de la entrega

  • País del destinatario

  • El proveedor de la red del destinatario

  • El cuerpo del mensaje

  • Cuánto tardó en llegar el mensaje

Y eso es sólo una parte. Se trata de una API muy detallada que le ofrece un control total sobre cuánta información se incluye en los informes generados.

¿Para qué productos se pueden obtener informes?

La API de Reports cubre SMS, Voice, Verify, Numbers Insight, Mensajes, Conversacionesy Reconocimiento Automático del Habla.

Además, puede elegir que sus informes muestren el uso entrante o saliente, es decir, la diferencia entre recibir una llamada de voz (entrante) y realizar una llamada de voz (saliente).

Solicitud de datos a través de Reports API

Existen dos tipos diferentes de solicitudes que puede realizar con la Reports API:

  • Sincrónico: Optimizado para la recuperación frecuente y periódica de pequeños lotes de datos de hasta aproximadamente 10.000 registros.

  • Asíncrono: Optimizado para consultas grandes y poco frecuentes que devuelven decenas de millones de registros.

Síncrono frente a asíncrono

Una forma de decidir qué método utilizar es analizar la frecuencia con la que desea recopilar datos.

Si necesita una vista actualizada o bajo demanda de sus datos y va a realizar solicitudes cada hora o cada día, el método de solicitud síncrono sería el adecuado.

Por otra parte, supongamos que desea recopilar datos con menos frecuencia, pero sabe que generará muchos registros a lo largo de un solo mes de uso. En ese caso, el método de solicitud asíncrona es la mejor opción.

Por término medio, el método de solicitud asíncrono tarda entre 5 y 10 minutos en generar y devolver 1 millón de registros.

Obtener un informe sincrónico

Empezaremos haciendo una petición síncrona de datos SMS durante 24 horas utilizando librerías estándar para Node.js y Python. No necesitas nada especial para estas peticiones, así que puedes adaptarlas para usar la librería HTTP que prefieras.

Solicitud Sincrónica Node.js

Solicite datos de hasta 24 horas utilizando 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();

Petición síncrona Python

Solicite datos de hasta 24 horas utilizando 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())

Solicitar datos de informes asíncronos

A continuación, haremos la misma petición de datos de SMS, pero esta vez esperamos que devuelva hasta 10 millones de registrospor lo que cambiaremos al método de petición asíncrona para esta parte. La forma en que funciona este proceso es algo así

  • Realiza una solicitud de datos de informe asíncrona, suministrando un callback_url para notificar que el informe está listo. A continuación, anote el request_id recibido en la respuesta.

  • (opcional) Compruebe el estado del informe solicitado, utilizando el botón request_id. Una vez completado, un informe con el estado SUCCESS también tendrá el informe download_url en la sección _links sección.

  • Recibir una petición HTTP en la carpeta callback_url. Esto contiene la sección _links que contiene el download_url para el informe.

  • Descargue el informe del download_url.

Solicitud asíncrona de Node.js

Realiza una petición para que se genere un informe asíncrono, utilizando 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();

Petición asíncrona en Python

Realice una solicitud para que se genere un informe asíncrono, utilizando 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())

Comprobar el estado de sus informes

Puede consultar el estado de sus informes en cualquier momento para comprobar si se han completado (en cuyo caso la descarga estará disponible) o si todavía se encuentran en un PENDING estado.

Comprobar el estado del informe con Node.js

Obtenga una actualización del estado de un informe asíncrono con 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();

Comprobar el estado del informe con Python

Obtener una actualización del estado de un informe asíncrono con 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())

Para los dos ejemplos anteriores, la respuesta será algo parecido a esto:

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

Tenga en cuenta la download_report URL especificada en la respuesta. Esa URL es un enlace a la versión descargable del informe (un archivo ZIP que contiene un CSV). Tiene hasta 72 horas para descargar el archivo antes de que se elimine de nuestros servidores, y tendrá que volver a ejecutar la consulta del informe para que se vuelva a generar.

Se necesitan credenciales para descargar el archivo de informe. un ejemplo en el portal para desarrolladores que muestra cómo hacerlo.

Buenas maneras de utilizar Reports API

La Reports API le proporciona la mayor cantidad de información que puede obtener de nosotros en relación con la actividad de sus cuentas (¡y subcuentas!). Esto significa que la API se presta a aplicaciones de tipo big data, como:

  • Visualización y análisis de datos mediante herramientas como Tableau.

  • Formar parte de una implementación de canalización de datos para almacenes de datos.

  • Detectar tendencias de tráfico, problemas o picos de costes fraudulentos a gran escala.

  • Proporcionar análisis en profundidad a los clientes sobre su actividad (a través de subcuentas).

  • Pruebas y gestión de campañas salientes (especialmente con SMS o Messages API).

Una vez que se tiene acceso a estos datos, hay muy pocos límites a lo que se puede hacer con ellos.

Lecturas complementarias

Si este post introductorio ha despertado su interés, entonces su siguiente parada debería ser la documentación completa de la API de Reports, así como la resumen principal de la Reports API donde hay aún más detalles sobre lo que contiene un informe generado.

Compartir:

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

Antiguo Director de Educación para Desarrolladores en Vonage. Con experiencia como desarrollador creativo, gestor de productos y organizador de jornadas de hacking, Martyn lleva trabajando como defensor de la tecnología desde 2012, tras haber pasado anteriormente por el mundo de la radiodifusión y las grandes discográficas. Educa y capacita a desarrolladores de todo el mundo.