API externe external-api
Description description
L’activité API externe récupère des données dans le workflow d’un système externe via un appel API HTTP.
Les points d’entrée de système externes peuvent être des point d’entrée API publics, des systèmes de gestion des clients ou des instances d’application sans serveur (ex. : Adobe I/O Runtime), pour ne citer que quelques catégories.
Les principales caractéristiques de cette activité sont les suivantes :
- Capacité de transmettre des données dans un format JSON à un point d’entrée API REST tiers
- Capacité de recevoir une réponse JSON, de la mapper sur des tables de sortie et de la transmettre en aval à d’autres activités de workflow
- Gestion des échecs avec une transition spécifique sortante
Remarques concernant la compatibilité descendante from-beta-to-ga
Avec la version 20.4 de Campaign Standard, la limite de taille des données des données de réponse http et les mécanismes de sécurisation de timeout de réponse ont été abaissés afin de s’aligner sur les bonnes pratiques - voir Limites et mécanismes de sécurisation. Ces modifications de mécanismes de sécurisation ne prendront pas effet dans les activités d’API externe existantes ; par conséquent, il est recommandé de remplacer les activités d’API externe existantes par de nouvelles versions dans tous les workflows.
Lorsque vous remplacez les activités d’API externe, ajoutez la nouvelle activité d’API externe au workflow, copiez manuellement les détails de la configuration, puis supprimez l’ancienne activité.
Limites et mécanismes de sécurisation guardrails
Les mécanismes de sécurisation suivants s’appliquent à cette activité :
- Limite de taille des données de réponse http de 5 Mo (remarque : il s’agit d’une modification par rapport à la limite de 50 Mo de la version précédente)
- Le timeout des demandes est de 1 minute (remarque : il s’agit d’une modification par rapport au timeout de 10 minutes de la version précédente.)
- Les redirections HTTP ne sont pas autorisées
- Les URL autres que HTTPS sont rejetées
- L’en-tête de demande "Accept: application/json" et l’en-tête de réponse "Content-Type: application/json" sont autorisés
Des mécanismes de sécurisation spécifiques ont été mis en place :
- Profondeur JSON maximale : limite la profondeur maximale d’un code JSON imbriqué personnalisé qui peut être traité à 10 niveaux.
- Longueur de clé JSON maximale : limite la longueur maximale de la clé interne générée à 255. Cette clé est associée à l’ID de colonne.
- Nombre maximum de clés JSON autorisées : limite à 150 le nombre total maximum de noms de propriétés JSON dupliqués, qui sont utilisés comme ID de colonne.
Configuration configuration
Placez une activité API externe dans votre workflow et ouvrez l’activité pour commencer la configuration.
Mapping entrant
Le mapping entrant est un tableau temporaire généré par une activité entrante précédente qui sera affichée et envoyée sous forme de code JSON dans l’interface utilisateur.
Selon ce tableau temporaire, l’utilisateur peut apporter des modifications aux données entrantes.
La liste déroulante Ressource entrante permet de sélectionner l’activité de requête qui crée le tableau temporaire.
La case à cocher Ajouter un paramètre de comptage ajoutera une valeur numérique pour chaque ligne provenant du tableau temporaire. Cette case à cocher est disponible uniquement si l’activité entrante génère un tableau temporaire.
La section Colonnes entrantes permet à l’utilisateur d’ajouter n’importe quel champ du tableau de transition entrante. Les colonnes sélectionnées sont les clés de l’objet de données. L’objet de données du code JSON est une liste de tableaux contenant les données des colonnes sélectionnées de chaque ligne du tableau de transition entrante.
La zone de texte Personnaliser le paramètre permet d’ajouter un code JSON valide avec des données additionnelles requises par l’API externe. Ces données additionnelles seront ajoutées à l’objet params du code JSON généré.
Mapping sortant
Cet onglet permet de définir l’exemple de structure JSON renvoyé par l’appel API.
L’analyseur JSON est conçu pour s’adapter aux types de motifs de structure JSON standard, à quelques exceptions près. Voici un exemple de modèle standard :{“data”:[{“key”:“value”}, {“key”:“value”},...]}
L’exemple de définition JSON doit présenter les caractéristiques suivantes :
- Les éléments de tableau doivent contenir des propriétés de premier niveau (les niveaux plus profonds ne sont pas pris en charge).
Les noms de propriété deviennent des noms de colonne pour le schéma de sortie du tableau temporaire de sortie. - Les éléments JSON à capturer doivent être imbriqués à 10 niveaux ou moins dans la réponse JSON.
- La définition du nom de colonne repose sur le premier élément du tableau "data".
La définition des colonnes (ajout/suppression) et la valeur de type de la propriété peuvent être éditées dans l’onglet Définition des colonnes.
Comportement de la case à cocher Aplatir :
La case à cocher Aplatir (par défaut : non cochée) est fournie pour indiquer si le fichier JSON doit être aplati ou non sur une carte clé/valeur.
-
Lorsque la case à cocher est désactivée (non cochée), l’exemple JSON est analysé pour la recherche d’un objet de tableau. L’utilisateur devra fournir une version abrégée du format JSON d’exemple de réponse de l’API afin qu’Adobe Campaign puisse déterminer exactement le tableau que l’utilisateur souhaite utiliser. Au moment de la création du workflow, le chemin d’accès à l’objet de tableau imbriqué sera déterminé et enregistré, de sorte qu’il puisse être utilisé au moment de l’exécution pour accéder à cet objet de tableau à partir du corps de réponse JSON reçu de l’appel API.
-
Lorsque la case à cocher est activée (cochée), l’exemple JSON est aplati et toutes les propriétés spécifiées dans l’exemple JSON fourni sont utilisées pour créer des colonnes du tableau temporaire de sortie et affichées dans l’onglet Définitions des colonnes. Notez que s’il existe un objet de tableau dans l’exemple JSON, tous les éléments de ces objets de tableau seront également aplatis.
Si l’analyse est validée, un message s’affiche. Il vous invite à personnaliser le mappage des données dans l’onglet « Définition des colonnes ». Dans d’autres cas, un message d’erreur s’affiche.
Exécution
Cet onglet vous permet de définir le point d’entrée de la connexion. Le champ URL vous permet de définir le point d’entrée HTTPS avec lequel Campaign Standard communiquera.
Si le point d’entrée l’exige, deux types de mécanismes d’authentification sont disponibles :
-
Authentification de base : entrez votre nom d’utilisateur / mot de passe dans la section En-tête(s) de demande.
-
Authentification OAuth : en cliquant sur Utiliser les paramètres de connexion définis dans un compte externe dans un compte externe, vous pouvez sélectionner un compte externe où l’ Authentication OAuth est définie. Pour plus d’informations, consultez la section Comptes externes.
Propriétés
Cet onglet permet de contrôler les propriétés générales de l’activité API externe, comme le libellé affiché dans l’interface utilisateur. L’identifiant interne n’est pas personnalisable.
Définition de colonne
L’onglet Définition des colonnes vous permet de définir précisément la structure des données de chaque colonne pour importer des données qui ne contiennent pas d’erreur et les faire correspondre aux types pré-existants de la base Adobe Campaign pour des opérations ultérieures.
Vous pouvez par exemple modifier le libellé d’une colonne, sélectionner son type (chaîne, nombre entier, date, etc.) ou encore définir le traitement des erreurs.
Pour plus d’informations, consultez la section Chargement de fichier.
Transition
Cet onglet permet d’activer la transition sortante et son libellé. Cette transition spécifique est utile si le délai d’expiration ou la payload dépasse la limite de taille des données.
Options d’exécution
Cet onglet est disponible dans la plupart des activités de workflow. Pour plus d’informations, consultez la section Propriétés d’une activité.
Test
Pour tester la fonctionnalité API externe avec un point d’entrée de test simple, vous pouvez utiliser Postman Echo : https://docs.postman-echo.com.
Résolution des problèmes
Deux types de messages de log ont été ajoutés à cette nouvelle activité de workflow : informations et erreurs. Ils peuvent vous aider à résoudre les problèmes potentiels.
Informations
Ces messages de log sont utilisés pour consigner des informations sur les points de contrôle utiles lors de l’exécution de l’activité de workflow.
Erreurs
Ces messages de log sont utilisés pour consigner des informations sur des conditions d’erreur inattendues peuvent entraîner l’échec de l’activité de workflow.
L’URL de l’API n’a pas pu être analysée (erreur : -2010’).
Remarque : cette erreur est consignée lorsque l’URL d’API échoue aux règles de validation.
L’hôte d’URL de l’API ne doit pas être ’localhost’ ni un littéral d’adresse IP (hôte d’URL : ’localhost’).
L’hôte d’URL de l’API ne doit pas être ’localhost’ ni un littéral d’adresse IP (hôte d’URL : ’192.168.0.5’).
L’hôte d’URL de l’API ne doit pas être ’localhost’ ni un littéral d’adresse IP (hôte d’URL : ’[2001]’).
Echec de la création du JSON du corps de la demande. Erreur lors de l’ajout de ’params’.
Echec de la création du JSON du corps de la demande. Erreur lors de l’ajout de ’data’.
La clé de l’en-tête HTTP est incorrecte (clé de l’en-tête : ’%s’).
Remarque : cette erreur est consignée lorsque la clé d’en-tête personnalisée échoue à la validation selon les RFC.
La valeur de l’en-tête HTTP est incorrecte (valeur de l’en-tête : ’%s’).
Remarque : cette erreur est consignée lorsque la valeur d’en-tête personnalisée échoue à la validation selon les RFC.
Elément JSON incorrect ou format inacceptable.
Remarque : ce message s’applique uniquement à l’analyse du corps de la réponse de l’API externe. Il est consigné lors de la tentative de validation de la conformité du corps de la réponse au format JSON mandaté par cette activité.
Lorsque l’activité échoue en raison de la réponse d’erreur HTTP 401 - Echec de l’activité (motif : ’HTTP - 401’)
Lorsque l’activité échoue en raison d’un appel interne en échec - Echec de l’activité (motif : ’iRc - -Nn’).
Lorsque l’activité échoue en raison d’un en-tête Content-Type non valide. - Echec de l’activité (motif : ’Content-Type - application/html’).