1. Créer le point de publication
Créez « REST API » avec la direction « Publier les données du flux ». Saisissez un nom, une version API et un identifiant, par exemple stock. L’adresse devient GET /api/v1/data/stock avec le préfixe de votre installation. Choisissez JSON, JSON Lines, CSV ou XML. Configurez le séparateur CSV ; pour XML, les noms des colonnes doivent être des noms d’éléments valides.
Un point protégé n’a pas besoin d’un secret de connexion distinct : le consommateur utilise son propre client API. Fixez l’âge maximal des données pour les résultats enregistrés. « Limites API » peut restreindre le nombre de lignes par réponse ; un paramètre limit supérieur à ce plafond est ramené à la valeur autorisée.
2. Relier le résultat dans un flux
Ajoutez « Publication de données API » depuis « API : réception et publication de données » et sélectionnez un point libre. Reliez son entrée au bloc dont la table doit être exposée. Il peut s’agir d’un résultat préparé par transformation ou du résultat d’une destination après écriture. Pour un routeur, choisissez la sortie voulue.
Le bloc termine sa branche et n’a pas de sortie. Un flux autorise un bloc de publication ; un point appartient à un seul flux publié. Réutiliser un point déjà occupé est refusé avec API_POINT_TAKEN. Enregistrez et publiez le flux. Avant publication, le point renvoie 409 API_ENDPOINT_NOT_READY; le mode de résultats enregistrés nécessite aussi une première exécution.
3. Choisir le mode de fraîcheur
« Résultats enregistrés de la dernière exécution » renvoie la table de la dernière exécution Production terminée, réussie ou partielle. GET n’exécute pas le flux. Organisez les actualisations par calendrier ou un autre mécanisme autorisé. Des données plus anciennes que le maximum configuré produisent 409 API_DATA_STALE; zéro désactive le contrôle de l’âge.
« Exécuter le flux à chaque requête » exécute Production sans participation interactive. Définissez une attente de 1 à 120 secondes et une réutilisation du résultat de 0 à 3600 secondes. Des paramètres d’exécution identiques peuvent réutiliser un résultat terminé ; des requêtes identiques simultanées attendent la même exécution. Le propriétaire de la clé doit pouvoir exécuter le flux et le client disposer de « Lecture ». La limite d’âge des données enregistrées ne s’applique pas dans ce mode.
4. Ajouter les paramètres API
Dans les propriétés du bloc, cliquez sur « Ajouter un paramètre ». Le nom commence par une lettre latine et contient jusqu’à 40 lettres, chiffres ou traits de soulignement ; offset, limit et run sont réservés. Ajoutez une description pour l’intégrateur. Un paramètre peut filtrer des lignes par un champ ou renseigner un paramètre d’exécution du flux ; ce dernier usage n’est disponible qu’en exécution à la demande.
Définissez le type — texte, nombre ou date —, le caractère obligatoire, les valeurs autorisées ou les bornes. Par exemple, warehouse filtre Warehouse et date filtre une date. Répéter warehouse=KYIV&warehouse=LVIV sélectionne plusieurs valeurs ; date_from et date_to définissent un intervalle inclusif. Les différents paramètres s’appliquent ensemble. Contrairement à la réception, le préfixe p. n’est pas pris en charge ici.
5. Lire les pages d’un même résultat
La requête ci-dessous suppose que vous avez configuré le paramètre warehouse. Ajoutez les en-têtes de clé et de HMAC selon les règles du client. Les réponses incluent X-Total-Rows, X-Run-Id, X-Run-Finished et ETag. Suivez Link ou X-Next-Offset pour une autre page, en conservant les paramètres et l’identifiant d’exécution.
GET /api/v1/data/stock?warehouse=KYIV&offset=0&limit=100
Authorization: Bearer API_KEY
X-UBC-Timestamp: UNIX_SECONDS
X-UBC-Signature: v1=HMAC_HEXSi une nouvelle exécution ne se termine pas à temps, 202 API_RUN_PENDING renvoie next, Location, Retry-After et run.id. Attendez puis appelez next : cette adresse contient run=... et ne démarre pas une nouvelle exécution. Envoyez If-None-Match avec un ETag inchangé pour recevoir 304.
6. Accès, erreurs et recette
Gardez le point protégé pour les données internes. « Point public — accès sans clé ni signature » l’ouvre à tous après confirmation ; une limite distincte par IP et la limite globale API restent applicables. La documentation technique et les autres routes ne deviennent pas automatiquement publiques.
Testez les paramètres valides et manquants, plusieurs pages, des données anciennes et un utilisateur sans autorisation. 400 API_PARAMETER_REQUIRED signifie un paramètre manquant ; API_PARAMETER_INVALID, une valeur invalide ; API_QUERY_UNKNOWN, un nom inconnu. Un champ absent produit 409 API_PARAMETER_FIELD; une exécution échouée, 502 API_RUN_FAILED. Vérifiez les nombres filtrés, les clés précises et run.id, plutôt que HTTP 200 seul.
En mode exécution, un point public lance le flux avec les droits de l’utilisateur qui l’a publié ; vérifiez-les avant d’activer l’accès. La référence du bloc « Publication de données API » énumère les paramètres du bloc.