Mon premier appel aux services Web

Modifié le Mar, 9 Sept. à 4:50 H

Pour vous familiariser avec les services Web de Dialog Insight, rien de mieux que se lancer dans le code dès maintenant. Nous allons donc réaliser ensemble un premier appel dans votre projet test. Pour cet exemple, nous utiliserons la méthode Contacts.Merge, idéale pour débuter. Cette méthode permet en un seul appel de créer un contact ou de mettre à jour ses informations s’il existe déjà. Dans cet article, nous allons vous aider à créer votre environnement et vous guiderons pour réaliser votre premier appel.

Lectures recommandées

Si vous commencez de zéro avec Dialog Insight, nous vous conseillons ces lectures pour mieux comprendre les possibilités de la plateforme Dialog Insight et des services Web :

Étape 1 : Créer un projet test

Quand on débute à faire des tests d'appels avec Dialog Insight, la meilleure précaution est de commencer par créer un projet test dédié. Cet environnement isolé joue le rôle de bac à sable : on peut y expérimenter, valider des appels API, simuler des campagnes ou manipuler des données sans risques celles qui sont réellement utilisées en production. Un projet test offre un espace de travail sécurisé où l’on peut faire des essais sans craindre d’envoyer un message accidentel à un client, de corrompre des données ou de fausser des statistiques. Contrairement à un projet réel, il n’a pas pour but de servir les opérations quotidiennes, mais bien de permettre aux développeurs de travailler librement, de vérifier leurs scripts et d’apprendre à utiliser la plateforme.

Il peut être tentant de se servir du projet déjà en production, mais les risques sont élevés. Une requête API mal configurée ou une automatisation pourrait déclencher un envoi de courriels ou de SMS à des destinataires réels. Des erreurs d’import ou de mise à jour pourraient modifier, voire effacer, des informations critiques. Même de simples enregistrements de test peuvent polluer vos rapports et vos indicateurs de performance. À cela s’ajoute la question légale : utiliser de vraies données personnelles dans des essais techniques peut poser un problème de conformité avec les lois, notamment avec le RGPD ou la Loi 25.

Option 1 : Créer un projet à partir de zéro

Rendez-vous dans votre compte et créez un nouveau projet :

Pour plus de détails sur les étapes de création de projet, consultez Créer un projet.

Option 2 : Dupliquer un projet existant

Rendez-vous dans la liste des projets et cliquez sur Dupliquer à la fin de la ligne du projet à dupliquer:

Peu importe l'option choisie, assurez-vous de donner un nom et une description à votre projet qui indiqueront explicitement qu'il s'agit d'un projet test (par exemple « Projet – TEST » ou « Sandbox API ») :

Bonnes pratiques pour un projet test

Lorsque vous importez des données dans ce projet, utilisez uniquement des données fictives, comme des adresses génériques ou des domaines réservés au test. Utilisez des adresses courriel génériques ou formatées pour vos tests (test1@example.com, api.demo@domain.test).
Créez des segments clairement identifiés comme « Tests » pour isoler vos enregistrements.
Si possible, configurez un domaine d’envoi réservé aux tests pour l'ensemble du compte.
Pensez aussi à limiter ou rediriger les envois pour que vos essais ne quittent jamais le cadre prévu.
Documentez la structure et les usages du projet test pour que toute l’équipe sache comment l’utiliser correctement. Un nettoyage régulier des données permettra également de garder l’environnement clair et facile à manipuler.

Étape 2 : Créer une clé pour les services Web

Les clés pour les services Web permettent à votre application ou à vos scripts d’interagir avec la plateforme via l’API. Concrètement, les clés servent à authentifier et à autoriser vos appels, que ce soit dans un projet test ou un projet servant à gérer vos données de contacts. Chaque clé donne des accès différents : projets, tables, services (endpoints). Avant de créer votre clé, il est important de comprendre son rôle, ses implications en matière de sécurité et les bonnes pratiques pour la gérer.

Pour commencer, créez une clé pour votre projet test. Cela vous permettra de vous familiariser avec le fonctionnement. Limitez la permission de cette clé au projet test pour éviter des actions involontaires dans les autres projets du compte de votre entreprise. Vous pouvez créer une clé distincte pour chaque environnement (développement, test, production).

→ Consulter la procédure pour créer une clé

Bonnes pratiques pour les clés de services Web

Limitez les permissions au strict nécessaire.
Nommez clairement les clés pour identifier rapidement leur usage.
Stockez les clés de façon sécurisée dans des variables d’environnement ou un gestionnaire de secrets, jamais en clair dans le code.
Documentez, dans votre dépôt ou wiki interne, quelles clés sont utilisées par quels services.
Changez vos clés périodiquement pour limiter les risques.
Supprimez immédiatement une clé si elle est compromise.
Générez des clés API spécifiques à l’environnement de test afin d’éviter les erreurs de configuration.

Étape 3 : Consulter le endpoint et la méthode

Rendez-vous d'abord dans la documentation pour l'environnement que votre compte utilise.

Liens vers la documentation

Canada : https://app.dialoginsight.com/fe/webservices/about
France : https://app.mydialoginsight.com/fe/webservices/about

À gauche, dans la liste des services Web, localisez le endpoint Contacts et cliquez sur la méthode Merge :Dans la documentation de chaque méthode, vous trouverez une description complète de la méthode ainsi que des exemples de requête et de réponses en JSON.

Étape 4 : Générer un exemple

Dans la page de description de Contacts.Merge, repérez le bouton Tester (il est un peu subtil) :

Dans l'éditeur de requête, rendez-vous dans le Mode avancé et cliquez sur Générer un exemple :

Étape 5 : Adapter l'exemple

L'exemple généré vous sert de base intéressante pour créer votre appel. Il ne vous reste qu'à ajouter les informations adaptées à votre cas.

Authkey

Lorsque vous avez créé votre clé de services Web, la clé générée possède les paramètres idkey et key dont vous devez ajouter les valeurs ici.

idProject

Pour savoir où trouver votre idProject, consultez cet article.

Records

Ajoutez les données des contacts à importer selon la structure mise en place dans votre projet.

L'exemple présente un cas fréquent de clé de projet avec courriel (key_f_email) dans lequel vous indiquez le contact à ajouter ou mettre à jour avec son courriel. La clé peut être différente dans votre projet. Il arrive que la clé soit un numéro de client.

→ En savoir plus sur les clés uniques et la gestion des doublons

Dans Data, les champs s'écrivent avec « f_ » suivi du code du champ de projet (la destination de la donnée). Vous pouvez trouver le code d'un champ dans la liste de votre projet accessible par Projet → Gestion des données → Champs de projet.« FirstName » devient donc « f_FirstName ».

Étape 6 : Envoyer la requête

Vous n'avez pas besoin d'utiliser d'URL dans l'interface de test. C'est ajouté en arrière-plan. Quoique l'interface se nomme test, les appels sont réellement envoyés au projet indiqué dans le idProject. Faites donc attention aux requêtes demandées ici.

Lorsque vous êtes prêt, cliquez sur Envoyer la requête :

Résultats

Si la réponse est positive et qu'il n'y a pas d'erreurs d'exécution, vous pourrez voir les contacts ajoutés dans la liste dans votre projet. Pour consulter la liste, rendez-vous dans Audience → Contacts.