Apresentando a Reports API da Vonage

Observação: Este artigo foi publicado originalmente quando a Reports API estava em fase beta. Temos o prazer de anunciar que a Reports API já está disponível para uso geral, oferecendo a você acesso a todos os seus relatórios nas áreas de Voice, Mensagens, Verify, Identity Insights e Video. Clique aqui para ver o anúncio de disponibilidade geral: A Reports API da Vonage já está disponível para o público em geral.

A Reports API da Vonage é uma API robusta que permite coletar dados sobre todas as atividades realizadas em sua Account.

Nesta postagem, veremos quais dados podem ser exportados, como você pode acessá-los tanto com JavaScript quanto com Python e o que o uso de uma API como essa ajuda você a entender.

Visão geral da Reports API

A Reports API é uma API que permite acessar todos os dados subjacentes gerados pelo uso de nossas outras APIs. Por exemplo, quando você envia um SMS da sua conta, essa ação é registrada, juntamente com as seguintes informações:

• O custo do envio da mensagem

• O status da entrega

• O país em que o destinatário se encontra

• A operadora de rede do destinatário

• O corpo da mensagem propriamente dito

• Quanto tempo a mensagem levou para ser entregue

E isso é só uma parte! É uma API muito detalhada que oferece controle total sobre a quantidade de informações incluídas nos relatórios gerados.

Para quais produtos é possível obter relatórios?

A Reports API abrange SMS, Voice, Verify, Análise de números, Mensagens, Conversase uso do Reconhecimento Automático de Fala.

Além disso, você pode optar por fazer com que seus relatórios mostrem o uso de chamadas recebidas ou realizadas — essa é a diferença entre receber uma chamada de voz (chamada recebida) e fazer uma chamada de voz (chamada realizada).

Solicitação de dados por meio da Reports API

Existem dois tipos diferentes de solicitações que você pode fazer com a Reports API:

• Síncrono: Otimizado para a recuperação frequente e periódica de pequenos lotes de dados com até aproximadamente 10.000 registros.

• Assíncrono: Otimizado para consultas grandes e pouco frequentes que retornam dezenas de milhões de registros.

Síncrono x Assíncrono

Uma maneira de decidir qual método usar é analisar com que frequência você deseja coletar dados.

Se você precisar de uma visão atualizada ou sob demanda dos seus dados e for fazer solicitações a cada hora ou a cada dia, o método de solicitação síncrona seria adequado.

Por outro lado, suponha que você queira coletar dados com menos frequência, mas saiba que irá gerar muitos registros ao longo de um único mês de uso. Nesse caso, o método de solicitação assíncrona é a melhor opção.

Em média, o método de solicitação assíncrona leva cerca de 5 a 10 minutos para gerar e retornar 1 milhão de registros.

Obter um relatório síncrono

Começaremos fazendo uma solicitação síncrona de dados de SMS ao longo de 24 horas, utilizando bibliotecas padrão para Node.js e Python. Você não precisa de nada especial para essas solicitações, portanto, pode adaptá-las para usar a biblioteca HTTP de sua preferência.

Solicitação síncrona no Node.js

Solicitar dados de até 24 horas usando o 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();

Solicitação síncrona em Python

Solicite dados de até 24 horas usando 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 dados de relatório assíncronos

A seguir, faremos a mesma consulta para dados de SMS, mas, desta vez, esperamos que ela retorne até 10 milhões de registros, por isso vamos mudar para o método de solicitação assíncrona nesta parte. O funcionamento desse processo é mais ou menos assim:

• Faça uma solicitação de dados de relatório assíncrona, fornecendo um callback_url para ser notificado quando o relatório estiver pronto. Em seguida, anote o request_id recebido na resposta.

• (opcional) Verifique o status do relatório solicitado, utilizando o request_id. Quando concluído, um relatório com o status SUCCESS também terá o relatório download_url na _links seção.

• Receber uma solicitação HTTP no callback_url. Ela contém a seção _links que contém o download_url para o relatório.

• Baixe o relatório no download_url.

Solicitação assíncrona no Node.js

Faça uma solicitação para que um relatório assíncrono seja gerado, usando o 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();

Solicitação assíncrona em Python

Faça uma solicitação para que um relatório assíncrono seja gerado, usando 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())

Como verificar o status dos seus relatórios

Você pode verificar o status dos seus relatórios a qualquer momento para saber se eles já foram concluídos (nesse caso, o download estará disponível) ou se ainda estão em PENDING estágio.

Verificar o status do relatório com o Node.js

Obter uma atualização do status de um relatório assíncrono com o 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();

Verificar o status do relatório com Python

Obter uma atualização do status de um relatório assíncrono com o 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())

Nos dois exemplos acima, a resposta será mais ou menos assim:

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

Observe a download_report URL especificada na resposta. Essa URL é um link para a versão do relatório disponível para download (um arquivo ZIP contendo um CSV). Você tem até 72 horas para baixar o arquivo antes que ele seja removido de nossos servidores; caso contrário, será necessário executar novamente a consulta do relatório para que ele seja regenerado.

São necessárias credenciais para baixar o arquivo do relatório; há um exemplo no Portal do Desenvolvedor que mostra como fazer isso.

Ótimas maneiras de usar a Reports API

A Reports API oferece a maior quantidade de informações que você pode obter conosco sobre a atividade em suas contas (e subcontas!). Isso significa que a API é ideal para aplicações do tipo big data, tais como:

• Visualização e análise de dados por meio de ferramentas como o Tableau.

• Participar da implementação de um pipeline de dados para data warehouses.

• Identificar tendências de tráfego, problemas ou picos de custos fraudulentos em grande escala.

• Fornecer análises detalhadas aos clientes sobre suas atividades (por meio de subcontas).

• Testar e gerenciar campanhas de envio (especialmente com APIs de SMS ou Messages API).

Uma vez que você tenha acesso a esses dados, há pouquíssimas limitações quanto ao que você pode fazer com eles.

Leitura complementar

Se este post introdutório despertou seu interesse, então sua próxima parada deve ser a documentação completa da Reports API, bem como a visão geral principal da Reports API , onde há ainda mais detalhes sobre o que está contido em um relatório gerado.