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

Einführung in die Vonage Reports API

Zuletzt aktualisiert am April 19, 2021
#nodejs
#python
#reports-api

Lesedauer: 4 Minuten

Anmerkung: Dieser Artikel wurde ursprünglich veröffentlicht, als sich die Reports API noch in der Beta war. Wir freuen uns, ankündigen zu können, dass die Reports API jetzt allgemein verfügbar ist, Damit haben Sie Zugriff auf alle Ihre Berichte in den Bereichen Voice, Messaging, Verify, Identity Insights und Video. Klicken Sie hier, um die Ankündigung der allgemeinen Verfügbarkeit zu sehen: Vonage Reports API ist jetzt allgemein verfügbar.

Die Vonage Reports API ist eine robuste API, die es Ihnen ermöglicht, Daten über alle Aktivitäten zu sammeln, die in Ihrem Account stattfinden.

In diesem Beitrag sehen wir uns an, welche Daten exportiert werden können, wie man sowohl mit JavaScript als auch mit Python darauf zugreifen kann und was die Verwendung einer solchen API zu verstehen hilft.

Reports API Übersicht

Die Reports API ist eine API, die Ihnen Zugriff auf alle zugrunde liegenden Daten gibt, die Ihre Nutzung unserer anderen APIs erzeugt. Wenn Sie zum Beispiel eine SMS von Ihrem Account aus versenden, wird diese Aktion zusammen mit den folgenden Daten aufgezeichnet:

  • Die Kosten für die Übermittlung der Nachricht

  • Der Lieferstatus

  • Das Land, in dem sich der Empfänger befindet

  • Der Netzanbieter des Empfängers

  • Der eigentliche Text der Nachricht

  • Wie lange die Zustellung der Nachricht dauerte

Und das ist nur ein Teil davon! Es ist eine sehr detaillierte API, die Ihnen die volle Kontrolle darüber gibt, wie viele Informationen in die erstellten Berichte aufgenommen werden.

Für welche Produkte können Sie Berichte erhalten?

Die Reports API umfasst SMS, Voice, Verify, Numbers Einsicht, Nachrichten, Unterhaltungenund Automatisierte Spracherkennung verwenden.

Außerdem können Sie wählen, ob Ihre Berichte die eingehende oder die ausgehende Nutzung anzeigen sollen - das ist der Unterschied zwischen einem eingehenden und einem ausgehenden Sprachanruf.

Anfordern von Daten über die Reports API

Es gibt zwei verschiedene Arten von Anfragen, die Sie mit der Reports API stellen können:

  • Synchron: Optimiert für den häufigen und regelmäßigen Abruf kleinerer Datenmengen von bis zu etwa 10.000 Datensätzen.

  • Asynchron: Optimiert für seltene, große Abfragen mit mehreren Millionen Datensätzen.

Synchron vs. Asynchron

Eine Möglichkeit, sich für eine Methode zu entscheiden, besteht darin, die Häufigkeit der Datenerfassung zu berücksichtigen.

Wenn Sie eine aktuelle oder On-Demand-Ansicht Ihrer Daten benötigen und diese stündlich oder täglich abrufen, ist die synchrone Abfragemethode angemessen.

Oder nehmen Sie an, Sie wollen weniger häufig Daten sammeln, wissen aber, dass Sie in einem einzigen Monat viele Datensätze erzeugen werden. In diesem Fall ist die asynchrone Abfragemethode die bessere Wahl.

Im Durchschnitt benötigt die asynchrone Abfragemethode etwa 5-10 Minuten, um 1 Million Datensätze zu erstellen und zurückzugeben.

Synchronen Bericht abrufen

Wir beginnen mit einer synchronen Abfrage von SMS-Daten über 24 Stunden unter Verwendung von Standardbibliotheken für Node.js und Python. Für diese Anfragen benötigen Sie nichts Besonderes, Sie können sie also an die HTTP-Bibliothek Ihrer Wahl anpassen.

Node.js Synchrone Anfrage

Abfrage von Daten für bis zu 24 Stunden mit 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();

Python Synchrone Anfrage

Abfrage von Daten für bis zu 24 Stunden mit 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())

Asynchrone Berichtsdaten anfordern

Als Nächstes werden wir dieselbe Anfrage für SMS-Daten stellen, aber dieses Mal erwarten wir, dass sie bis zu 10 Millionen DatensätzeDaher wechseln wir für diesen Teil zur asynchronen Abfragemethode. Dieser Prozess funktioniert in etwa so:

  • Stellen Sie eine Anforderung für asynchrone Berichtsdaten, indem Sie eine callback_url für die Benachrichtigung, dass der Bericht fertig ist. Notieren Sie dann die request_id in der Antwort erhalten.

  • (fakultativ) Überprüfen Sie den Status des angeforderten Berichts, indem Sie den request_id. Sobald ein Bericht mit dem Status SUCCESS wird auch der Bericht download_url im Abschnitt _links Abschnitt.

  • Empfangen Sie eine HTTP-Anfrage an der callback_url. Diese enthält den Abschnitt _links der die download_url für den Bericht enthält.

  • Laden Sie den Bericht von der Website download_url.

Node.js Asynchrone Anfrage

Stellen Sie eine Anforderung für einen asynchronen Bericht, der mit Node.js erstellt werden soll:

#!/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();

Python Asynchrone Anfrage

Fordern Sie die Erstellung eines asynchronen Berichts mit Python an:

#!/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())

Überprüfen des Status Ihrer Berichte

Sie können jederzeit den Status Ihrer Berichte überprüfen, um festzustellen, ob sie abgeschlossen sind (in diesem Fall steht der Download zur Verfügung) oder sich noch in einem PENDING Zustand befinden.

Berichtsstatus mit Node.js prüfen

Abrufen eines Status-Updates für einen asychronen Bericht mit 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();

Berichtsstatus mit Python prüfen

Abrufen eines Status-Updates für einen asynchronen Bericht mit 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())

Für die beiden oben genannten Beispiele sieht die Antwort etwa so aus:

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

Beachten Sie die download_report URL, die in der Antwort angegeben ist. Diese URL ist ein Link zur herunterladbaren Version des Berichts (eine ZIP-Datei mit einer CSV-Datei). Sie haben bis zu 72 Stunden Zeit, die Datei herunterzuladen, bevor sie von unseren Servern entfernt wird und Sie Ihre Berichtsabfrage erneut ausführen müssen, um sie neu zu generieren.

Zum Herunterladen der Berichtsdatei sind Anmeldedaten erforderlich. ein Beispiel auf dem Entwicklerportal das zeigt, wie man das macht.

Großartige Möglichkeiten zur Verwendung der Reports API

Die Reports API bietet Ihnen die größte Menge an Informationen, die Sie von uns über die Aktivitäten auf Ihren Accounts (und Unter-Accounts!) erhalten können. Das bedeutet, dass sich die API für Big-Data-Anwendungen eignet, wie z. B.:

  • Datenvisualisierung und -analyse mit Tools wie Tableau.

  • Beteiligung an einer Datenpipeline-Implementierung für Data Warehouses.

  • Erkennen von Verkehrstrends, Problemen oder betrügerischen Kostenspitzen in großem Maßstab.

  • Bereitstellung detaillierter Analysen der Kundenaktivitäten (über Unterkonten).

  • Testen und Verwalten von Outbound-Kampagnen (insbesondere mit SMS oder Messages APIs).

Wenn Sie erst einmal Zugang zu diesen Daten haben, sind Ihnen kaum Grenzen gesetzt, was Sie damit machen können.

Weitere Lektüre

Wenn dieser einleitende Beitrag Ihr Interesse geweckt hat, dann sollten Sie als nächstes die vollständige Dokumentation für die Reports API sowie die Hauptübersicht der Reports API wo es noch mehr Details darüber gibt, was in einem generierten Bericht enthalten ist.

Teilen Sie:

https://a.storyblok.com/f/270183/250x250/d0444194cd/martyn.png
Martyn DaviesVonage Ehemalige

Ehemaliger Direktor für Entwicklerschulung bei Vonage. Mit einem Hintergrund als kreativer Entwickler, Produktmanager und Organisator von Hack-Days arbeitet Martyn seit 2012 als Befürworter der Technologie, nachdem er zuvor beim Rundfunk und bei großen Plattenfirmen tätig war. Er bildet Entwickler auf der ganzen Welt aus und unterstützt sie.