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.

NOTE
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

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é.

NOTE
Vous ne pourrez pas copier sur les valeurs de l’en-tête spécifiques aux activités, car elles sont masquées dans l’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.
CAUTION
L’activité d’API externe a pour objectif de récupérer les données de l’ensemble de la campagne (dernier ensemble d’offres, derniers scores, etc.), et non de récupérer des informations spécifiques pour chaque profil, car cela peut entraîner le transfert de grandes quantités de données. Si le cas pratique le requiert, la recommandation consiste à utiliser l'activité Transfert de fichier.

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

NOTE
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é.

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.

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’.
Nouvelle tentative de l’URL d’API ’%s’ en raison de %s en %d ms, tentative %d.
Nouvelle tentative de l’URL d’API ’https://example.com/api/v1/web-coupon?count=0’ en raison de HTTP - 401 en 2364 ms, tentative 2.
Transfert du contenu depuis ’%s’(%s / %s).
Transfert du contenu depuis ’https://example.com/api/v1/web-coupon?count=2’ (1234/1234).
Utilisation du jeton d’accès mis en cache pour l’identifiant de fournisseur ‘%s’.
Utilisation du jeton d’accès mis en cache pour l’identifiant de fournisseur ‘EXT25’. Remarque : EXT25 est l’identifiant (ou le nom) du compte externe.
Jeton d’accès récupéré sur le serveur pour l’identifiant de fournisseur ‘%s’.
Jeton d’accès récupéré sur le serveur pour l’identifiant de fournisseur ‘EXT25’. Remarque : EXT25 est l’identifiant (ou le nom) du compte externe.
Actualisation du jeton d’accès OAuth en raison d’une erreur (HTTP : ‘%d’).
Actualisation du jeton d’accès OAuth en raison d’une erreur (HTTP : ‘401’).
Erreur lors de l’actualisation du jeton d’accès OAuth (erreur : ‘%d’).
Erreur lors de l’actualisation du jeton d’accès OAuth (erreur : ‘404’).
Impossible de récupérer le jeton d’accès OAuth à l’aide du compte externe spécifié pour la tentative %d, nouvelle tentative en %d ms.
Impossible de récupérer le jeton d’accès OAuth à l’aide du compte externe spécifié pour la tentative 1, nouvelle tentative en 1387 ms.

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’).

WKF-560278 - « Erreur lors de l’initialisation de l’aide OAuth (erreur : ‘%d’) ».
Cette erreur indique que l’activité n’a pas pu initialiser l’aide interne OAuth2.0, en raison d’une erreur lors de l’utilisation des attributs configurés dans le compte externe pour initialiser l’aide.
WKF-560279 - « La clé de l’en-tête HTTP n’est pas autorisée (clé de l’en-tête : ‘%s’). »
Ce message d’avertissement (pas d’erreur) indique que le compte externe OAuth 2.0 a été configuré pour ajouter des informations d’identification en tant qu’en-tête HTTP, mais que la clé d’en-tête utilisée n’est pas autorisée car il s’agit d’une clé d’en-tête réservée.
WKF-560280 - Le compte externe de l’identifiant ‘%s’ est introuvable.
Le compte externe de l’identifiant ‘EXT25’ est introuvable. Remarque : cette erreur indique que l’activité est configurée pour utiliser un compte externe qui est introuvable. Il est probable que cette erreur se produise lorsque le compte a été supprimé de la base de données. Il est donc peu probable qu’elle se produise dans des conditions d’exploitation normales.
WKF-560281 - Le compte externe de l’identifiant ‘%s’ est désactivé.
Le compte externe de l’identifiant ‘EXT25’ est désactivé. Remarque : cette erreur indique que l’activité est configurée pour utiliser un compte externe, mais que ce compte a été désactivé (ou marqué comme inactif).
WKF-560282 - Protocole non pris en charge.
Cette erreur indique que le compte externe associé à l’activité n’est pas un compte externe OAuth2.0. Il est donc peu probable que cette erreur se produise à moins que des modifications manuelles soient effectuées sur la configuration de l’activité ou que celle-ci soit endommagée.
WKF -560283- Impossible de récupérer le jeton d’accès OAuth.
La cause la plus courante de cette erreur est une mauvaise configuration du compte externe (par ex. utilisation du compte externe sans tester la connexion). Il est possible que l’URL/les informations d’identification du compte externe aient été modifiées.
CRL-290199 - Impossible d’atteindre la page à l’adresse : %s.
Ce message d’erreur s’affiche sur l’écran de l’interface utilisateur des comptes externes lors de la configuration d’OAuth. Elle indique que l’URL du serveur d’autorisations externe est soit incorrecte, soit modifiée ou que la réponse du serveur est Page introuvable.
CRL-290200 - Informations d’identification incomplètes/incorrectes.
Ce message d’erreur s’affiche sur l’écran de l’interface utilisateur des comptes externes lors de sa configuration d’OAuth. Elle indique que les informations d’identification sont incorrectes ou qu’il manque d’autres informations d’identification requises pour se connecter au serveur d’authentification.
recommendation-more-help
3ef63344-7f3d-48f9-85ed-02bf569c4fff