Saltar al contenido principal

Ingesta de eventos a través de la API de streaming

Introducción​

Utilice esta API para enviar datos de eventos a una canalización para su procesamiento, filtrado, enriquecimiento y enrutamiento.

Este punto final admite la ingesta en tiempo real de alto rendimiento y admite eventos JSON estructurados y semiestructurados. Es ideal para aplicaciones en la nube, microservicios, dispositivos IoT o cualquier sistema que emita telemetría.

Funciones de la API​

  • Enviar registros y métricas directamente a una canalización
  • Normalizar y enriquecer los datos antes de enviarlos aguas abajo
  • Reducir los costes mediante el filtrado o el muestreo temprano
  • Crear canalizaciones flexibles sin dependencia de un proveedor

Antes de empezar​

Asegúrese de que dispone de:

  • Un token de API con permisos de ingestión
  • Un ID de flujo
  • Cargas útiles de eventos en formato JSON
  • curl o Postman instalado

Descripción general de la canalización​

flowchart LR
    A["Aplicación en la nube / microservicio"] --> B["Streaming Ingest API"]
    B --> C["Capa de procesamiento<br/> • Análisis sintáctico<br/> • Enriquecimiento<br/> • Enmascaramiento"]
    C --> D["Motor de enrutamiento<br/> • Filtros<br/> • Muestreo<br/> • Reglas"]
    D --> E{{"Destinos:<br/>S3 / SIEM / Elastic / Snowflake"}}

Punto final de ingestión​

POST /v1/streams/ingest

Encabezados de solicitud​

EncabezadoValorObligatorioDescripción
AuthorizationBearer <token>SíToken de API
Content-Typeapplication/jsonSíCarga útil JSON
X-Stream-Id<your-stream-id>SíCanalización de destino

Cuerpo de la solicitud​

{
  "timestamp": "2025-02-12T14:32:15Z",
  "source": "payments-app",
  "event": {
    "transactionId": "txn_30921",
    "status": "approved",
    "latency_ms": 182,
    "amount": 499,
    "currency": "USD"
  },
  "metadata": {
    "env": "prod",
    "team": "payments"
  }
}

Notas​

  • timestamp: formato ISO 8601
  • event: Datos del evento principal (pares clave-valor)
  • Tamaño máximo de la carga útil: 1 MB

Respuesta​

200 OK​

{
  "status": "accepted",
  "ingested_bytes": 527,
  "stream_id": "a0c3b4de-1923-4ff1-8dba-f92ad912d20f"
}

400 Bad request​

Problemas comunes:

  • JSON no válido
  • Formato de marca de tiempo incorrecto
  • Faltan campos de origen o evento
  • La carga útil supera el tamaño máximo
{
  "error": "invalid_format",
  "detail": "The 'timestamp' field must be a valid ISO 8601 string."
}

401 Unauthorized​

  • Falta el token o ha caducado.

429 Rate limited​

  • Reducir la tasa de solicitudes o los eventos por lotes.

Ejemplo de cURL​

curl -X POST "https://api.example.com/v1/streams/ingest" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Stream-Id: $STREAM_ID" \
  -d @event.json

Casos de uso comunes​

  • Ingestión de registros de microservicios
  • Transmisión de telemetría desde dispositivos IoT
  • Normalización de eventos de sistemas distribuidos
  • Enrutamiento de eventos enriquecidos a SIEM, S3, Elastic o Snowflake
  • Canalizaciones de detección de fraudes o anomalías en tiempo real

Solución de problemas​

SíntomaCausa probableSolución
No se muestran eventos en la canalizaciónID de flujo incorrectoCopie el ID de flujo correcto
Carga rechazadaJSON no válidoValide con jq
Campos que faltanDiscrepancia en la estructura anidadaRevise las reglas de análisis
Alta latenciaCargas grandes o procesamiento por lotesReduzca el tamaño de los lotes

Próximos pasos​

  • Añada reglas de análisis, enmascaramiento o enriquecimiento
  • Enrute los datos a múltiples destinos
  • Reduzca los costes con muestreo o filtrado
  • Cree métricas y paneles de control para el canal