Show Menu
SUJETS×

API externe

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.
Pour des raisons de sécurité, l’utilisation de JSSP n’est pas prise en charge dans Campaign Standard. Si vous devez exécuter du code, vous pouvez appeler une instance Runtime Adobe I/O via l’activité API externe.
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

Transition de la version bêta à la version GA

Avec Campaign Standard version 20.3, la fonctionnalité API externe est passée de la version bêta à la version GA (General Availability).
Par conséquent, si vous utilisiez les activités API externe bêta, vous devez les remplacer par des activités API externe GA dans tous les workflows.  Les worfklows qui utilisent la version bêta de l’API externe cesseront de fonctionner à partir de la version 20.3.
Lorsque vous remplacez les activité API externe, ajoutez la nouvelle activité API externe au workflow, copiez manuellement les détails de la configuration, puis supprimez l'ancienne activité.
Vous ne pourrez pas copier sur les valeurs de l’en-tête, car elles sont masquées dans l’activité.
Ensuite, reconfigurez d’autres activités dans le workflow qui pointent vers et/ou utilisent les données de l’activité API externe bêta pour pointer vers et/ou utiliser les données de la nouvelle activité API externe à la place. Exemples d’activités : diffusion email (champs de personnalisation), activité d’enrichissement, etc.

Limitations et garde-fous

Les garde-fous suivants s'appliquent à cette activité :
  • Taille limite de 50 Mo de données de réponse http (5 Mo recommandés)
  • Le timeout des demandes est de 10 minutes
  • 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
A compter de la version Campaign 20.4, la limite de taille des données de réponse http et les garde-fous de délai d’expiration de réponse seront abaissés à 5 Mo et 1 minute, respectivement. Bien que cette modification n'affecte que les nouvelles activités d'API externe, il est fortement recommandé que les mises en oeuvre actuelles de l'activité d'API externe s'alignent sur ces nouvelles garde-fous pour suivre les meilleures pratiques.
Des garde-fous spécifiques ont été mis en place pour le JSON :
  • 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.
L’activité n’est pas prise en charge par la structure JSON en tant que :
  • Combinaison d’un objet de tableau avec d’autres éléments non issus de tableaux
  • L’objet de tableau JSON est imbriqué dans un ou plusieurs objets de tableau intermédiaire.
L’activité API externe est destinée à la récupération des données à l’échelle de la campagne (dernier ensemble d’offres, derniers scores, etc.), et non à la récupération d’informations spécifiques pour chaque profil, ce qui peut entraîner le transfert de grandes quantités de données. Si le cas pratique requiert cela, la recommandation consiste à utiliser l’activité Transfert de fichier .

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 HTTPS qui enverra des données à ACS. Au besoin, vous pouvez saisir des informations d’authentification dans les champs ci-dessous.

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

Cet onglet s’affiche lorsque le format des données de réponse est complété et validé dans l’onglet Mapping sortant.
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é .

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. En particulier, les messages de log suivants sont utilisés pour consigner la première tentative et une tentative de reprise (et la raison de l’échec de la première tentative) d’accès à l’API.
Format du message Exemple
Appel de l’URL d’API ’%s’.
Appel de l’URL d’API ’https://example.com/api/v1/web-coupon?count=2’.
Reprise de l’URL d’API ’%s’, la tentative précédente a échoué (’%s’).
Reprise de l’URL d’API https://example.com/api/v1/web-coupon?count=2’, la tentative précédente a échoué (’HTTP - 401’).
Transfert du contenu depuis ’%s’(%s / %s).
Transfert du contenu depuis ’https://example.com/api/v1/web-coupon?count=2’ (1234/1234).

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.
Code - Format du message Exemple
WKF-560250 - Le corps de la demande d’API a dépassé la limite (limite : ’%d’).
Le corps de la demande d’API a dépassé la limite (limite : ’5242880’).
WKF-560239 - La réponse de l’API a dépassé la limite (limite : ’%d’).
La réponse de l’API a dépassé la limite (limite : ’5242880’).
WKF-560245 - L’URL de l’API n’a pas pu être analysée (erreur : ’%d’).
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.
WKF-560244 - L’hôte d’URL de l’API ne doit pas être ’localhost’ ni un littéral d’adresse IP (hôte d’URL : ’%s’).
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]’).
WKF-560238 - L’URL d’API doit être une URL (https) sécurisée (URL demandée : ’%s’).
L’URL d’API doit être une URL (https) sécurisée (URL demandée : ’https://example.com/api/v1/web-coupon?count=2’).
WKF-560249 - Echec de la création du JSON du corps de la demande. Erreur lors de l’ajout de ’%s’.
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’.
WKF-560246 - La clé de l’en-tête HTTP est incorrecte (clé de l’en-tête : ’%s’).
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 .
WKF-560248 - La clé de l’en-tête HTTP n’est pas autorisée (clé de l’en-tête : ’%s’).
La clé de l’en-tête HTTP n’est pas autorisée (clé de l’en-tête : ’Accept’).
WKF-560247 - La valeur de l’en-tête HTTP est incorrecte (valeur de l’en-tête : ’%s’).
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 .
WKF-560240 - La propriété ’%s’ de la payload JSON est incorrecte.
La propriété ’blah’ de la payload JSON est incorrecte.
WKF-560241 - Elément JSON incorrect ou format inacceptable.
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é.
WKF-560246 - Echec de l’activité (motif : ’%s’).
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’).