Aller au contenu principal

Acquisition d'événements via l'API de diffusion en continu

Introduction​

Utilisez cette API pour envoyer des données d'événements dans un pipeline en vue de leur traitement, de leur filtrage, de leur enrichissement et de leur acheminement.

Ce point de terminaison prend en charge le haut débit, l'ingestion en temps réel et prend en charge les événements JSON structurés et semi-structurés. Il est idéal pour les applications cloud, les microservices, les appareils IoT ou tout système émettant de la télémétrie.

Pourquoi utiliser cette API ?​

  • Envoyer des journaux et des métriques directement dans un pipeline
  • Normaliser et enrichir les données avant de les envoyer en aval
  • Réduire les coûts en filtrant ou en échantillonnant en amont
  • Construire des pipelines flexibles sans dépendance à l'égard d'un fournisseur

Avant de commencer​

Assurez-vous d'avoir

  • Un Token API avec des permissions d'ingestion
  • Un Identifiant de flux
  • Des charges utiles d'événement formatées en JSON
  • curl ou Postman installé

Aperçu du pipeline​

flowchart LR
    A["Cloud App / Microservice"] --> B["Streaming Ingest API"]
    B --> C["Couche de traitement<br/> - Parsing<br/> - Enrichissement<br/> - Masking"]
    C --> D["Moteur de routage<br/> - Filtres<br/> - Echantillonnage<br/> - Règles"]
    D --> E{{"Destinations:<br/>S3 / SIEM / Elastic / Snowflake"}}

Point d'arrivée de l'ingestion​

POST /v1/streams/ingest

En-têtes de requête​

En-têteValeurRequisDescription
AuthorizationBearer <token>OuiJeton API
Content-Typeapplication/jsonOuiCharge utile JSON
X-Stream-Id<votre-flux-id>OuiPipeline cible

Corps de la requête​

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

Notes​

  • timestamp : Format ISO 8601
  • event : Données de l'événement principal (paires clé-valeur)
  • Taille maximale de la charge utile : 1 MB

Réponse​

200 OK​

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

400 Bad request​

Problèmes courants :

  • JSON non valide
  • Format d'horodatage incorrect
  • Champs source ou event manquants
  • La charge utile dépasse la taille maximale
{
  "error" : "invalid_format",
  "detail" : "Le champ 'timestamp' doit être une chaîne ISO 8601 valide."
}

401 Non autorisé​

  • Token manquant ou expiré.

429 Taux limité​

  • Réduire le taux de demande ou regrouper les événements.

Exemple 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

Cas d'utilisation courants​

  • Ingestion de logs à partir de microservices
  • Streaming de télémétrie à partir d'appareils IoT
  • Normalisation des événements provenant de systèmes distribués
  • Routage d'événements enrichis vers SIEM, S3, Elastic ou Snowflake
  • Pipelines de détection de fraude ou d'anomalie en temps réel.

Dépannage​

SymptômeCause probableRéparation
Aucun événement n'apparaît dans le pipelineMauvais ID de fluxCopier le bon ID de flux
400 Bad RequestJSON non valideValider en utilisant jq
Champs manquantsMauvaise correspondance des structures imbriquéesRevoir les règles d'analyse
Haute latenceCharges utiles importantes ou lotsRéduire la taille du lot

Prochaines étapes​

  • Ajouter des règles d'analyse, de masquage ou d'enrichissement
  • Acheminer les données vers plusieurs destinations
  • Réduire les coûts grâce à l'échantillonnage ou au filtrage
  • Élaborer des mesures et des tableaux de bord pour le pipeline