1. Créer une connexion à la ressource
Dans « Connexions → REST API », choisissez « Appeler une API externe ». Définissez un nom explicite, l’adresse HTTPS de base du service et un chemin relatif de ressource tel que /orders. Une connexion décrit une ressource et une méthode de requête. Créez une connexion distincte pour une autre ressource ou méthode afin que la finalité et les autorisations de chaque intégration restent explicites.
N’ajoutez pas de chaîne de requête après un point d’interrogation dans le chemin. Saisissez les paramètres de base à raison d’un name=value par ligne ; un bloc source peut ajouter ses propres paramètres. Saisissez les en-têtes supplémentaires sous la forme Name: value. Les secrets, y compris Authorization, vont dans les champs d’authentification dédiés, pas dans les en-têtes ordinaires.
2. Configurer l’authentification et le réseau
Choisissez une méthode prise en charge par le service externe : sans authentification, Basic, Bearer, clé API dans un en-tête ou OAuth2 client credentials. Basic nécessite un utilisateur et un mot de passe ; la clé API, un nom d’en-tête et une clé ; OAuth2, une adresse de jeton, un Client ID, un secret client et le scope éventuel. Une clé API entrante Data Bridge ne remplace pas les identifiants du service externe.
Vérifiez DNS, le port, la confiance du certificat TLS et les droits du compte. Pour une ressource interne, utilisez une route réseau approuvée ou un UBC Agent configuré. « Test » vérifie l’accessibilité ; sa réussite ne garantit pas le droit de lire chaque ressource ou d’écrire. Enregistrez la connexion après examen du diagnostic.
3. Lire et analyser la réponse
Utilisez GET ou POST pour une source. La lecture POST possède son propre corps de requête dans le format choisi ; elle diffère d’une destination qui envoie des lignes de table. Définissez explicitement le format de réponse ou détectez-le via Content-Type : JSON, XML, CSV/TSV ou JSON Lines. Vérifiez l’encodage, le séparateur et les en-têtes.
Pour la réponse ci-dessous, le chemin des enregistrements est data.items. XML nécessite un chemin d’éléments tel que ./item; les attributs parents peuvent être inclus si nécessaire. Les objets imbriqués deviennent des colonnes séparées par des points. Ajoutez la connexion comme source et prévisualisez ses champs avant de construire un filtre ou un mappage.
{"data":{"items":[{"orderId":"ORD-1042","status":"open","amount":1250}]}}4. Configurer la pagination complète
Respectez le contrat du service : une réponse unique, un lien suivant dans JSON/XML, un en-tête Link , un numéro de page ou un décalage. Pour les numéros de page, définissez le nom du paramètre, la première page et la taille ; pour le décalage, son paramètre et la taille du lot. Pour un lien suivant dans le corps, indiquez le chemin exact ; le lien doit rester sur le même serveur.
Limitez le nombre de pages et la taille de la table de réponse. Un service utilisant page et page_size, par exemple, ne peut pas être lu comme une pagination par décalage, même si la première page semble correcte. Vérifiez au moins deux pages, une dernière page incomplète et l’absence de clés en double. Les liens suivants du corps ne s’appliquent pas à CSV ou JSON Lines.
5. Envoyer des lignes par une destination
Pour écrire, choisissez POST, PUT ou PATCH et le format JSON, XML, formulaire ou CSV. La destination construit le corps à partir de sa table d’entrée. JSON envoie un objet de ligne ou un tableau d’objets ; vous pouvez définir la clé du tableau de lot. XML nécessite un élément de ligne et une racine de lot. Les données de formulaire ne prennent en charge qu’une requête par ligne. CSV inclut les en-têtes et les valeurs.
Les requêtes individuelles peuvent utiliser un chemin tel que /orders/{{orderId}}. Adaptez la taille des lots à l’API, préparez un petit test et vérifiez la destination par clé. La signification de PUT ou PATCH relève du service externe : ne supposez pas une opération upsert automatique ou l’idempotence si son contrat ne les définit pas.
6. Vérifier les échecs et le journal
Dans « Paramètres → API → Limites API », l’administrateur contrôle les nouvelles tentatives, les délais, Retry-After et le disjoncteur du serveur, qui suspend temporairement les appels après des échecs répétés. Les erreurs temporaires de lecture peuvent être retentées ; une écriture ne l’est que si elle n’a certainement pas été acceptée, par exemple en cas d’échec avant établissement de la connexion ou de HTTP 429. Une réponse d’écriture perdue reste incertaine : rapprochez d’abord la destination.
Utilisez « Requêtes API » dans le menu contextuel du bloc pour consulter la méthode, l’adresse, l’état et la durée. Testez 401/403, les réponses vides, les changements de schéma et les limites de pages. Comparez le journal au résultat du bloc et au nombre final d’enregistrements. La réception contrôlée de requêtes externes utilise une autre direction : un point d’entrée API.