Uso de la API de Reports con Laravel

Introducción

En API de Reports de Vonage brinda análisis de uso poderosos y filtrables; este tutorial muestra cómo integrarla con Laravel para generar informes sincrónicos y asincrónicos. Por lo tanto, si usas mucho, por ejemplo, Voice API o Messages API, puedes obtener estadísticas desde tu panel de la API de Vonage. Sin embargo, esto tiene sus limitaciones, ya que sólo puedes obtener los registros de los últimos 30 días. Como alternativa, puedes usar Reports API, que abrirá puntos finales de API para profundizar en tu uso, agregar parámetros específicos para filtrar datos o crear informes mucho más grandes de manera asincrónica. En lugar de 30 días, puede recuperar registros de los últimos 13 meses, o de los últimos 90 días si consulta datos de Video. Si desea utilizar Reports API, se le cobrará en función del número de registros que se incluyan en los informes.

Después de leer este desglose, es posible que ya seas un usuario intensivo de Vonage que requiere precios personalizados: en este caso, te recomendamos que te comuniques con tu administrador de cuenta para obtener un plan ilimitado. Nuestra recomendación general al elegir precios es cambiar al plan ilimitado si vas a buscar más de 1 millón de eventos al mes o 12 millones de registros al año.

En este artículo, vamos a utilizar Laravel para obtener estos datos como un ejemplo.

Requisitos previos

• Compositor

• PHP8.2+

• Instalador de Laravel

• ngrok

• Una cuenta 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.

Instalación de Laravel

El instalador de Laravel utiliza el mecanismo de Composer create-project para crear código repetitivo. Crea un nuevo directorio en tu máquina de desarrollo y ejecuta laravel install reports-api-demo. El instalador te dará un par de opciones - puedes seleccionar las predeterminadas aquí, y omitir la opción Laravel Starter Kits, ya que sólo queremos demostrar cómo manejamos los datos.

Establecer rutas

Para mantener las cosas lo más simple posible, vamos a tener tres rutas que corresponden a las tres formas diferentes en que se pueden implementar los informes. Estas rutas serán las siguientes:

• Alcanza un GET punto final que genera un informe síncrono que vuelve a tu aplicación, y escupirá el resultado

• Alcanza un GET que lanza una solicitud POST solicitud a Vonage de un informe asincrónico, con una URL de devolución de llamada que será

• A POST punto final al que Vonage responderá con tu informe asíncrono

Primera ruta: Crear un informe sincrónico

Vaya a su directorio routes/web.php y añada el siguiente código:

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

(Para los más avispados, sí, son claves de API falsas; oculta siempre tus datos sensibles!). Para una mejor idea de cómo manejar sus variables de entorno, consulte este artículo del blog.

En lugar de utilizar controladores, estamos añadiendo la lógica en el cierre de la ruta. Pulsando /report en tu aplicación se lanzará una petición al Reports API usando tu clave y secreto (puedes encontrarlos en tu Dashboard) y volcará la respuesta.

En esta solicitud, el informe sólo nos devolverá eventos de la SMS API, ya que hemos filtrado por ese producto en los parámetros de consulta. Esta API ofrece muchas opciones de consulta:

• SMS

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

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

• Entender los Numbers

• Verify

• In-App Messaging

• API de red

• Video

Esto es adecuado para pequeños volúmenes de datos, pero ¿qué ocurre cuando se necesitan millones de filas? Ahí es donde entra en juego el informe asíncrono.

Segunda vía: crear informes asíncronos

Millones de registros supondrían demasiada carga tanto para el cliente como para el servidor. Por lo tanto, puede POST una solicitud con parámetros de consulta del informe en el cuerpo JSON, con una URL de devolución de llamada para entregar un webhook cuando se complete. Como Vonage necesitará un punto final al cual enviar los datos del informe, deberás exponer tu aplicación a Internet. La forma más rápida de hacerlo es utilizando ngrok, que hace exactamente esto. Una vez que tengas ngrok instaladoejecútelo para exponer su aplicación y anote la URL.

Necesitamos un endpoint para recibir el informe. De momento, como demostración, sólo volcará los datos al archivo de registro de la aplicación.

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

A continuación, necesitamos un nuevo GET para iniciar la petición asíncrona:

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

Reemplace su clave API y el secreto de nuevo con su vivo dashboard y sustituya el campo callback_url con tu URL de ngrok, más /async agregado para que Vonage POST a la ubicación correcta. Accede a esta GET solicitud en tu navegador, y el informe se activará. Es importante tener en cuenta que los registros son cobrables por fila a menos que tenga una cuenta gestionada, así que asegúrese, mientras prueba esta implementación, de que no está a punto de golpear los servidores con millones de registros si los tiene y sólo sigue esto para probar.

Eventualmente (dependiendo del tamaño del informe) podrá navegar a storage/logs/laravel.log y ver los datos del informe asíncrono.

Visualización del estado de un informe asíncrono

Es posible que desee comprobar que no se ha perdido una devolución de llamada - digamos, por ejemplo, si hubo un error de análisis que significaba que el informe fue enviado a una URL no válida. Querrá ver el estado y, si se ha completado, descargar el informe. Para ello, vaya al punto final de comprobación de informes.

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 respuesta le dará toda la información que necesita. Siempre que request_status es SUCCESSpodrá extraer el enlace de descarga del campo download_report campo 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"
           }
       }
}

Conclusión

Y ahí lo tiene, ¡una forma totalmente asíncrona de consultar todas sus Comunicaciones de la Plataforma Cloud! La posibilidad de consultar por Account ID también le permite opciones adicionales: si usted es el usuario principal, entonces utilizará su API Key. Sin embargo, puede que sea un revendedor de comunicaciones, en cuyo caso, ahora tiene la posibilidad de generar informes personalizados por subcuenta. Esto también resulta especialmente útil para emitir facturas a clientes como revendedor. También puede utilizar Reports API para supervisar e identificar sus propios patrones de solicitudes potencialmente maliciosas y bloquear números utilizando la funcionalidad Fraud Defender.