Tâche du service Web

À propos de la tâche de service Web

La tâche Service Web est utile si vous avez de l’expérience de l’API et que vous souhaitez déclencher différents flux de travail dans le logiciel Qualtrics, ou vers un service Web externe, lorsque le répondant termine l’enquête. Par exemple, si votre enquête collecte les informations de contact du répondant, une tâche de service Web peut utiliser l’appel d’API de création de contact pour ajouter le répondant à une liste de contacts.

Nous vous recommandons également de consulter ces pages liées aux services Web pour obtenir de l’aide et de l’arrière-plan :

• Plateforme pour développeurs Qualtrics
• Méthodes de service Web
• Documentation API
• Transmission d’informations avec des chaînes de requêtes
• Texte inséré

Configuration d’une tâche de service Web

Selon la manière dont vous préférez mettre en forme les paramètres du corps, la configuration sera légèrement différente. Si vous utilisez le format JSON ou XML, saisissez votre corps dans la section Corps. Si vous préférez le codage URL, vous pouvez ajouter des paramètres comme chaîne de requête à la zone URL.

1. Créez un workflow (ou sélectionnez-en un existant) dans votre projet ou dans la page Workflows autonomes.
   
2. Assurez-vous d’être dans la section Vos workflows.
3. Cliquez sur Créer un workflow.
4. Déterminez la planification ou l’événement qui déclenche votre tâche. (Voir comparaison.)
5. Cliquez sur Ajouter une tâche et sélectionnez Service Web.
   
6. Sélectionnez votre méthode d’authentification. Vous avez le choix :
   
   • Authentifié : exécution d’une demande de service Web authentifié. Vos options d’authentification incluent Basic (avec un mot de passe et un nom d’utilisateur), une clé API et OAuth.
   • Non authentifié : exécuter une demande de service Web sans authentification.
7. Cliquez sur Suivant.
8. Si vous avez sélectionné une demande authentifiée, sélectionnez vos identifiants d’autorisation dans la liste ou cliquez sur Ajouter un compte utilisateur pour ajouter de nouveaux identifiants. Pour plus d’informations, voir Ajout d’informations d’autorisation.
   
   Astuce Qualtrics : vous pourrez sélectionner tous les identifiants que vous avez précédemment ajoutés, ou les identifiants ajoutés par un Administrateur de la Marque dans l’onglet Extensions.
9. Cliquez sur Suivant.
10. Si vous avez une demande au format curl-formaté, vous pouvez l’importer pour configurer automatiquement votre service Web. Voir la section Utilisation des commandes Curl pour plus de détails.
    
11. Si vous le souhaitez, ajoutez un récapitulatif de tâches en haut de votre tâche. Il s’agit d’une description expliquant l’objectif de la tâche.
12. Sélectionnez la méthode Request de votre service Web. Pour plus d‘informations sur chaque méthode, voir Méthodes de service Web.
    
    Astuce Qualtrics : si vous utilisez l’API Qualtrics, la documentation vous indiquera le type de demande à utiliser.
    Attention : les tâches de service Web n’autorisent aucune redirection d’URL pour les requêtes non GET. Une seule redirection est autorisée pour les demandes GET.
13. Saisissez l’URL de votre demande.
    Astuce Qualtrics : vous pouvez limiter les domaines auxquels la tâche de service Web peut se connecter en indiquant les domaines dans vos paramètres de domaine d’extension.
14. Si vous le souhaitez, cliquez sur Ajouter un en-tête pour ajouter un en-tête. Indiquez la clé et la valeur. Pour supprimer un en-tête, cliquez sur l’icône de corbeille en regard de l’en-tête.
    Astuce Qualtrics : utilisez l’icône de texte inséré, {a}, pour insérer dutexte inséré afin d’extraire des valeurs des réponses à l’enquête ou des tâches précédentes dans le flux de travail.
    Attention : si vous utilisez l’API Qualtrics, vous devez inclure votre jeton API dans l’en-tête. Voir Ajouter un en-tête pour les demandes d’API Qualtrics pour plus d’informations.
    Attention : pour les requêtes POST, PUT et PATCH, vous devez spécifier un type de données pour chaque couple clé-valeur.
    Attention : les tâches de service Web ne prennent actuellement pas en charge les commentaires/textes dans le corps contenant les séquences d’échappement.
15. Si vous avez choisi post, put, ou patch, vous devrez choisir le format de votre corps. Les options incluent JSON, encodé par URL, XML et Texte brut.
    
    
    Astuce : le texte brut ne peut être spécifié qu’en tant que texte libre. Lorsque vous utilisez l’option de texte libre JSON, les entrées ne sont pas échappées. Cela signifie, par exemple, qu’une saisie de texte inséré contenant des guillemets doubles ou des caractères de nouvelle ligne (exemple : \n) rendra le corps JSON non valide et ne s’exécutera pas correctement. Une alternative est d’utiliser l’option des paires clé-valeur ou d’utiliser une tâche de code pour nettoyer ou échapper le texte à injecter dans la tâche de service Web.
16. Déterminez la manière dont vous voulez indiquer le corps de votre demande. Vous pouvez ajouter le corps en tant que couples clé-valeur ou texte libre.
17. Si vous avez sélectionné des paires clé-valeur, ajoutez la clé et sa valeur associée. Cliquez sur Ajouter une paire clé-valeur pour ajouter des paramètres supplémentaires.
18. Sélectionnez un Type de données.
    • Booléen : sélectionnez ce type de données si vos données ont l’une des deux valeurs possibles.
    • JSON : sélectionnez ce type de données si vos données sont au format JSON.
    • Nombre : sélectionnez ce type de données si vos données sont numériques.
    • Chaîne : sélectionnez ce type de données si vos données sont au format texte.
    • Valeur par défaut du système : sélectionnez ce type de données si vous voulez utiliser le type de données natif pour vos données. Si un type de données est introuvable, le type par défaut est Chaîne.
      Astuce Qualtrics : nous vous recommandons de sélectionner l’un des autres types de données pour vous assurer que vos données sont correctement transférées.
      Attention : les paires clé-valeur qui ont été configurées avant le 16 septembre 2022 auront un type de données Par défaut du système.
    Astuce Qualtrics : le champ Type de données est disponible uniquement lorsque vous sélectionnez JSON et des paires clé-valeur dans les étapes 13-14.
19. Sélectionnez ce qui se passe si le type de données ne peut pas être transtypé.
    • Ne transtypez pas un type de données et marquez-le en tant qu’erreur : Si le type de données ne peut pas être transtypé, aucun type de données ne sera transtypé et la tâche échouera. Vous pouvez le voir dans l’onglet Historique d’exécution.
    • Convertir le type de données en valeur par défaut du système : Si le type de données ne peut pas être transtypé, le type de données sera défini sur Valeur par défaut du système.
20. Si vous avez sélectionné Texte libre, saisissez vos paramètres de corps dans le format que vous avez sélectionné.
    
    Attention : vous ne devez pas laisser cette zone vide ou avoir des clés sans valeurs. À la place, n’incluez pas le champ ou saisissez le terme “null” pour indiquer des valeurs vides. SAP vous recommande d’exclure la zone.
21. Pour tester votre service Web, cliquez sur Exécuter le test.
    
    Astuce Qualtrics : après avoir cliqué sur Exécuter le test, le résultat de votre demande s’affiche, vous indiquant si elle a réussi ou non, et le fichier JSON ou XML qui en résulte, s’il a réussi.
22. Cliquez sur Ajouter un chemin personnalisé pour ajouter des chemins JSON ou XML. Ces chemins vous permettent d’utiliser les résultats de votre service Web dans du texte inséré pour être utilisé avec d’autres tâches de votre flux d’opérations, telles qu’une tâche de code. Si vous avez testé votre service Web, vous pouvez avoir automatiquement des valeurs ici, car Qualtrics les retirera automatiquement des résultats.
    Astuce Qualtrics : cliquez sur Ajouter un chemin personnalisé pour ajouter des chemins supplémentaires, ou cliquez sur la corbeille à côté d’un chemin pour le supprimer.
23. Lorsque vous avez terminé de configurer votre workflow, cliquez sur Sauvegarder.

Ajout d’informations d’identification d’autorisation

Cette section explique comment ajouter des identifiants d’autorisation pour la tâche de service Web. Vous pouvez ajouter des identifiants à l’aide de la méthode Basic, API Key ou OAuth 2.0. Pour ajouter des identifiants, cliquez sur Ajouter un compte utilisateur dans la fenêtre de sélection des références de connexion.

Basique

L’authentification de base nécessite que vous vous connectiez avec le nom d’utilisateur et le mot de passe de votre compte.

1. Donnez un Nom à vos identifiants. Ceci est uniquement destiné à des fins d’organisation.
2. Sélectionnez Base comme type de connexion.
3. Saisissez le nom d’utilisateur requis pour l’authentification.
4. Saisissez le mot de passe pour l’authentification.
5. Cliquez sur Connecter un compte.

Clé API

L’authentification par clé API vous permet de vous authentifier à l’aide d’un jeton API statique.

1. Donnez un Nom à votre compte. Ceci est uniquement destiné à des fins d’organisation.
2. Sélectionnez le type de connexion Clé API.
3. Saisissez le jeton d’API utilisé pour l’authentification.
4. Cliquez sur Connecter un compte.

OAuth 2.0

L’autorisation OAuth2.0 évite d’avoir à utiliser des jetons API statiques ou un nom d’utilisateur et un mot de passe de base pour l’intégration à des plateformes tierces. La tâche de service Web prend en charge deux types d’autorisation OAuth2.0 différents : le code d’autorisation et les identifiants client.

Vous pouvez utiliser l’autorisation OAuth 2.0 pour une intégration transparente à de nombreuses plateformes tierces. L’implémentation du service Web Qualtrics suit la spécification OAuth officielle. Cependant, certains systèmes externes peuvent avoir des configurations légèrement différentes entraînant des incompatibilités avec l’autorisation OAuth 2.0 dans la tâche de service Web.

Les intégrations suivantes sont des exemples qui ont été entièrement vérifiés pour fonctionner avec OAuth 2.0 :

• Salesforce à l’aide de la méthode du code d’autorisation.
• Jira à l’aide de la méthode du code d’autorisation.
• Zoom à l’aide de la méthode de code d’autorisation.

Pour vous authentifier à l’aide d’OAuth 2.0 :

1. Donnez un Nom à votre compte. Ceci est uniquement destiné à des fins d’organisation.
2. Sélectionnez OAuth comme type de connexion.
3. Sélectionnez votre type d’autorisation ou la manière dont le jeton d’accès est récupéré. Vous pouvez choisir :
   • Code d’autorisation
   • Identifiants client
4. Saisissez l’ ID client et la clé secrète client.
5. Saisissez le point de terminaison du jeton.
6. Si vous avez sélectionné le code d’autorisation comme type d’attribution, saisissez le point de terminaison d’autorisation.
7. Cliquez sur Connecter un compte.

Renommage de &amp ; suppression des identifiants

Pour modifier le nom de vos identifiants, cliquez sur les trois points en regard du compte. Pour supprimer des identifiants, cliquez sur Supprimer le compte.

Ajout d’un en-tête pour les demandes d’API Qualtrics

Lorsque vous utilisez l’API Qualtrics, vous devez inclure votre jeton d’API comme en-tête dans votre service Web.

1. Configurez votre tâche de service Web, sélectionnez vos identifiants et votre demande.
   
2. Dans la section En-têtes, saisissez X-API-TOKEN comme Clé.
3. Pour la valeur, cliquez sur l’icône de texte inséré, {a}.
4. Sélectionnez vos identifiants dans la liste.
   

TLS mutuel

La sécurité de la couche de transport mutuel (mTLS) est une couche de sécurité supplémentaire facultative en plus des mécanismes d’authentification d’API standard (tels que le jeton API ou OAuth). TLS mutuel garantit à la fois que la personne qui se connecte à une API/un service Web et l’API/le service Web lui-même ont un trafic sécurisé et crypté dans les deux sens. Une fois que mTLS est activé, toutes les demandes doivent présenter le certificat client approprié pour que les demandes aboutissent. Si un appelant effectue une demande à l’aide d’un certificat client non valide ou manquant, l’API qu’il tente d’appeler bloquera la demande.

Conditions

Chaque service varie selon qu’il prend en charge mTLS et dans quel(s) format(s) il fournit des informations clés. La prise en charge de mTLS est garantie uniquement pour les services qui répondent à nos besoins :

• Indiquez une clé privée.
• La clé privée peut être mise en forme dans PKCS8.
• Fournir un certificat
• Le certificat peut être formaté en X.509.

Les API publiques Qualtrics prennent en charge mTLS comme décrit ci-dessus.

mTLS est uniquement pris en charge pour les services Web authentifiés créés dans les flux de travail. Les trois méthodes d’authentification sont prises en charge (Basic, API key et OAuth2.0).

Ajout de mTLS

1. Créez votre tâche de service Web.
   
2. Sélectionnez Authentifié.
   
3. Cliquez sur Suivant.
4. Ajoutez un compte utilisateur.
   
   Astuce Qualtrics : un Administrateur d’entreprise peut se connecter à un compte à l’aide de la page Extensions.
   
5. Sélectionnez un type de connexion et renseignez vos identifiants.
   
6. Sélectionnez Activer mTLS.
7. La clé privée peut être considérée comme l’identifiant unique du client qui tente de se connecter. Cette valeur doit être au format PKCS8.
   Astuce Qualtrics : si votre clé est dans un format différent, vous pouvez modifier ce format à l’aide d’un autre programme.
   Astuce Qualtrics : si vous prévoyez d’utiliser l’API Qualtrics avec votre service Web, consultez notre documentation API sur mTLS. Cette documentation vous montrera comment tirer la clé privée. Lorsque vous collez la valeur dans Qualtrics, vous devrez inclure des tirets indiquant « commencer clé privée » et « clé privée finale ».
8. La clé publique est le certificat mTLS. Cette valeur doit être au format X.509.
   Astuce Qualtrics : si vous prévoyez d’utiliser l’API Qualtrics avec votre service Web, consultez notre documentation API sur mTLS. Cette documentation vous montrera comment extraire le certificat. Lorsque vous collez la valeur dans Qualtrics, vous devrez inclure des tirets indiquant « commencer le certificat » et « terminer le certificat ».
9. Lorsque vous avez terminé, cliquez sur Connecter un compte.
10. Poursuivez la configuration de votre service Web.

Utilisation des commandes Curl

Les commandes Curl sont l’une des nombreuses façons de faire des requêtes HTTP, et sont un outil précieux pour transmettre des informations entre elles via des URL. Vous pouvez importer une commande curl pendant que vous configurez votre tâche pour renseigner automatiquement différentes configurations de service Web.

De nombreux documents API fournissent souvent des exemples curls que vous pouvez utiliser. Pouvoir copier et importer ces commandes peut ainsi rendre la configuration du service Web beaucoup plus rapide et plus facile.

Pour quelques exemples de demandes curl, regardez à droite sur chacun de ces documents d’API :

• Accéder à la liste de distribution
• Créer une distribution de rappel
• Mettre à jour la transaction de contact
• Répertorier les utilisateurs du groupe

Pour une requête GET, la commande curl peut être aussi simple que curl https://api.example.com/parameters. Pour les commandes curl qui ne sont pas aussi simples que cela, nous fournirons des paramètres communs.

Paramètres de commande Curl pris en charge

Voici quelques-uns des paramètres curl pris en charge par la tâche de service Web Qualtrics :

Paramètres d’en-tête communs

Ci-dessus, nous avons mentionné que vous pouvez utiliser des commandes curl pour définir des en-têtes. Les en-têtes servent divers objectifs dans la communication HTTP, tels que la fourniture d’informations sur la requête et le contrôle de l’authentification. Les en-têtes spécifiques que vous utilisez dépendent des exigences de l’application ou de l’API que vous utilisez.

Voici quelques exemples de paramètres d’en-tête :

Paramètres non pris en charge

Les paramètres curl qui ne figurent pas dans la liste ci-dessus ne sont pas pris en charge. Voici quelques exemples de formats de commande curl que les tâches du service Web Qualtrics ne prennent pas en charge :

• --cookie pour envoyer des cookies avec la demande.
• --L ou --emplacement pour les redirections suivantes.
• --max-time pour définir la durée maximale de la requête.
• --o ou --output pour enregistrer la réponse dans un fichier.
• --non sécurisé pour permettre des connexions non sécurisées.
• --A ou --user agent pour spécifier l’agent utilisateur.

Importation de commandes Curl

1. Lors de la configuration de votre tâche de service Web, cliquez sur Importer cURL.
   
2. Collez votre commande curl dans la zone.
   
   Attention : Veillez à inclure votre méthode HTTP dans votre requête curl, en particulier si vous copiez une commande curl depuis une autre plateforme.
   Astuce Qualtrics : gardez un œil sur certaines parties de la demande que vous devez remplir avec vos propres informations. Par exemple, dans la capture d’écran ci-dessus, vous remplaceriez “Clé API” par votre jeton API.

   Astuce Qualtrics : vous pouvez ajouter une commande dans une seule chaîne ou marquer des sauts de ligne à l’aide du caractère d’échappement ( \ ). Nous ne prenons pas en charge les échappements d’autres lignes (par exemple, ^ ). Voici un exemple de commande curl avec des caractères d’échappement pris en charge :

   curl https://www.google.com/accounts/test \
   -d accountType=GOOGLE \
   -d source=Google-cURL-Exemple \
   -d service=lh2

3. Cliquez sur Importer.
4. Les zones du service Web seront renseignées automatiquement.

FAQ