Choisir un mode de livraison

La classification s’exécute de façon asynchrone : vous soumettez une vidéo, Gaard la traite, et le résultat devient disponible un peu plus tard. Cette page explique les trois façons de récupérer ce résultat depuis Gaard, afin que vous puissiez choisir celle qui convient à votre architecture.

Il existe deux modèles :

Vous récupérez le résultat quand vous êtes prêt : l’interrogation (polling).
Gaard vous pousse le résultat dès qu’il est prêt : les webhooks ou la livraison SFTP.

Chaque résultat (niveau de risque, labels, scores et extrait annoté) est associé à un classify_id. Quelle que soit la méthode choisie, vous recevez le même résultat sous-jacent.

Interrogation (polling)

L’interrogation est l’option la plus simple : après avoir soumis une vidéo, vous appelez GET /api/result/<classify_id> jusqu’à ce que le statut soit done.

Vous maîtrisez le rythme. Rien n’a besoin d’être accessible depuis Internet : votre système n’émet que des requêtes HTTPS sortantes.
Le même payload partout. Le JSON renvoyé par GET /api/result/<classify_id> a la même forme qu’une classification synchrone (POST /api/classify?sync=true) et que celle envoyée par les webhooks : un seul analyseur couvre donc toutes les méthodes.
Le compromis, c’est la latence et le trafic. Vous n’apprenez que le résultat est prêt qu’à votre prochaine interrogation, et un intervalle court génère de nombreuses requêtes qui renvoient « pas encore terminé ».

L’interrogation est une bonne première intégration et le bon choix lorsque les rappels entrants ne sont pas possibles dans votre environnement. Voir Endpoints pour le détail des requêtes et des réponses.

Webhooks

Un webhook inverse le sens : lorsqu’une classification se termine, Gaard envoie une requête HTTP POST à un endpoint que vous exploitez, contenant le résultat au format JSON.

Latence minimale. La livraison est liée à la fin du traitement : aucun intervalle d’interrogation à attendre.
Vous exploitez un récepteur. Vous avez besoin d’un endpoint HTTPS que Gaard peut joindre.
La livraison se fait au mieux (best-effort). Gaard envoie un seul POST par endpoint configuré, ne réessaie pas, ne considère pas une réponse non-2xx comme un échec à réessayer, et n’ajoute ni signature ni en-tête d’authentification. Protégez votre endpoint en amont et rendez votre traitement idempotent.

Les webhooks se configurent par flow. Pour la configuration, le payload et les recommandations côté récepteur, voir Webhooks.

Livraison SFTP

La livraison SFTP écrit le résultat sur un serveur que vous contrôlez sous forme de fichiers, plutôt que par un appel HTTP. À mesure que chaque classification du flow se termine, Gaard se connecte à votre serveur SFTP/FTP et y dépose soit la vidéo annotée, soit les images d’instantanés.

Basée sur des fichiers, pas sur un endpoint. Vous exploitez un serveur SFTP/FTP au lieu d’un récepteur HTTP : un choix naturel pour les systèmes de gestion vidéo et les consommateurs par lots ou hors ligne.
Des fichiers, pas du JSON. Ce qui arrive sur le serveur est du média (un extrait .mp4 ou des instantanés JPEG), pas le résultat JSON. Optez pour l’interrogation ou les webhooks si vous avez besoin du résultat structuré.
La livraison se fait au mieux. Un transfert échoué est journalisé, pas réessayé.

Pour la configuration et les fichiers exacts qui sont écrits, voir Livraison SFTP.

Comparaison

	Interrogation	Webhooks	Livraison SFTP
Sens	Vous récupérez	Gaard pousse	Gaard pousse
Transport	HTTPS `GET`	HTTPS `POST`	Écriture de fichier SFTP/FTP
Latence	Selon votre intervalle d’interrogation	Quasi temps réel	Quasi temps réel
Vous devez exploiter	Rien en entrant	Un endpoint HTTPS	Un serveur SFTP/FTP
Vous recevez	Résultat JSON	Résultat JSON	Fichiers vidéo ou instantanés
Garantie de livraison	À la demande, aussi fiable que votre interrogation	Au mieux, une tentative, sans réessai	Écriture de fichier au mieux
Portée	Par requête	Par flow	Par flow
Idéal pour	Une première intégration, ou les réseaux restreints	Les pipelines événementiels	Les consommateurs par fichiers, VMS et par lots

Choisir

Commencez par l’interrogation si vous intégrez pour la première fois, ne pouvez pas accepter de connexions entrantes, ou souhaitez maîtriser explicitement le moment où vous récupérez les résultats.
Passez aux webhooks dès que vous exploitez un service HTTP et souhaitez un traitement événementiel quasi temps réel, sans interrogation répétée.
Utilisez la livraison SFTP lorsque votre consommateur est basé sur des fichiers : un système de gestion vidéo, une archive de preuves, ou une tâche par lots qui ingère des extraits et des images plutôt que du JSON.
Combinez-les. Vous pouvez interroger et configurer des webhooks en même temps, et la livraison par webhook ne désactive pas GET /api/result/<classify_id>. Configurer plusieurs destinations est la façon de diffuser un résultat vers plusieurs systèmes.

Étapes suivantes

Webhooks : configurer la livraison en push et concevoir un récepteur fiable.
Livraison SFTP : livrer les résultats sous forme de fichiers vers votre propre serveur.
Plateformes d’alarme : connecter Azursoft, Evalink, Prysm et SIA DC-09.