Modèle d’article

A propos de la Tâche Service Web

La tâche Service Web est utile si vous avez de l’expérience avec l’API et que vous souhaitez déclencher différents flux de travail au sein du logiciel Qualtrics, ou vers un service Web externe, lorsque la personne interrogée termine l’enquête. Par exemple, si votre enquête recueille les coordonnées de la personne interrogée, une tâche de service web peut utiliser l’appel API de création de contact pour ajouter la personne interrogée à une liste de tâches.

Nous vous recommandons également de consulter ces pages relatives aux services web pour plus d’assistance et d’informations :

• Qualtrics Developer Hub
• Méthodes des services 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 formater vos paramètres corporels, 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 l’encodage URL, vous pouvez ajouter des paramètres sous forme de chaîne de requête dans le champ URL.

1. Créez un flux de travail (ou sélectionnez un flux existant) dans votre projet ou dans la page autonome Flux de travail.
   
2. Assurez-vous d’être dans la section Vos flux de travail.
3. Cliquez sur Créer un flux de travail.
4. Déterminez l’horaire ou l’évènement qui déclenche votre tâche.(Voir une comparaison)
5. Cliquez sur Ajouter une tâche et sélectionnez WebService.
   
6. Choisissez votre méthode d’authentificateur. Vos options comprennent :
   
   • Authentificateur: Effectuer une demande de service web authentificateur. Vos options d’authentificateur sont les suivantes : basique (avec un mot de passe et un nom d’utilisateur), clé API et OAuth.
   • Non authentificateur: Effectuer une demande de service web sans authentificateur.
7. Cliquez sur Suivant.
8. Si vous avez sélectionné une demande authentifiée, sélectionnez vos informations d’identification d’autorisation dans la liste ou cliquez sur Ajouter un compte utilisateur pour ajouter de nouvelles informations d’identification. Pour plus d’informations, voir Ajout de justificatifs d’autorisation.
   
   Astuce : Dans l’onglet Extensions, vous pouvez sélectionner les informations d’identification que vous avez précédemment ajoutées ou celles qui ont été ajoutées par un Administrateur de l’organisation.
9. Cliquez sur Suivant.
10. Si vous disposez d’une requête formatée en curl, 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ésumé de la Tâche en haut de votre tâche. Il s’agit d’une description expliquant l’objectif de la tâche.
12. Choisissez la méthode Request de votre service web. Voir Méthodes de service Web pour plus d’informations sur chaque méthode.
    
    Astuce : Si vous utilisez l’API Qualtrics, la documentation vous indiquera le type de requête à utiliser.
    Attention : Les tâches de WebService n’autorisent pas les redirections d’URL pour les demandes autres que GET. Une seule redirection est autorisée pour les demandes GET.
13. Saisissez l’URL de votre demande.
    Astuce : Vous pouvez limiter les domaines auxquels la tâche de service web peut se connecter en spécifiant 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. Spécifiez la clé et la valeur. Pour supprimer un en-tête, cliquez sur l’icône de la corbeille située à côté de l’en-tête.
    Astuce : Utilisez l’icône de texte inséré, {a}, pour insérer du texte 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 clé API dans l’en-tête. Voir Ajouter un en-tête pour les requêtes de l’API Qualtrics pour plus d’informations.
15. Si vous avez choisi post, put ou patch, vous devrez choisir le format de votre corps. Les options incluent JSON, URL-Encoded, XML et Texte en clair.
    
    
16. Déterminez comment vous souhaitez spécifier le corps de votre demande. Vous pouvez ajouter le corps sous forme de paires clé-valeur ou de texte libre.
17. Si vous avez sélectionné des paires clé-valeur, ajoutez la clé et la valeur qui lui est associée. Cliquez sur Ajouter une paire clé-valeur pour ajouter des paramètres supplémentaires.
    Attention : Pour les requêtes POST, PUT et PATCH, vous devez spécifier un type de données pour chaque paire clé-valeur.
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.
    • Système par défaut : Sélectionnez ce type de données si vous souhaitez utiliser le type de données natif pour vos données. Si un type de données n’est pas trouvé, le type String sera utilisé par défaut.
      Astuce : Nous vous recommandons de sélectionner l’un des autres types de données pour vous assurer que vos données sont correctement moulées.
      Attention : Les paires clé-valeur configurées avant le 16 septembre 2022 auront un type de données ” System Default”.
    Astuce : Le champ Type de données n’est disponible que lorsque vous sélectionnez JSON et Paires clé-valeur aux étapes 13-14.
19. Sélectionnez ce qui se passe si le type de données ne peut pas être converti.
    • Ne pas convertir un type de données et signaler une erreur : Si le type de données ne peut pas être converti, aucun type de données ne sera converti et la tâche échouera. Ceci est visible dans l’onglet Historique des exécutions.
    • Convertir le type de données en valeur par défaut du système : si le type de données ne peut pas être converti, il sera défini comme valeur par défaut du système.
20. Si vous avez sélectionné Texte libre, saisissez les paramètres de votre corps dans le format choisi.
    
    Attention : Ce champ ne doit pas être vide ou comporter des clés sans valeur. Au lieu de cela, il faut soit ne pas inclure le champ du tout, soit saisir le terme “null” pour indiquer les valeurs vides. Nous recommandons d’exclure le champ.
    Astuce : Si une tâche de service web rencontre un corps JSON invalide, la tâche n’échouera pas. Au lieu de cela, le JSON invalide sera converti en une chaîne de caractères et enregistré en tant que propriété “text” dans un nouvel objet JSON. Ainsi, vous pourrez voir le texte invalide une fois le traitement de la tâche terminé.
    Attention : Les tâches de service web ne prennent pas actuellement en charge les commentaires.
21. Pour tester votre service web, cliquez sur Exécuter le test.
    
    Astuce : Après avoir cliqué sur Exécuter le test, le résultat de votre requête s’affichera, vous indiquant s’il a réussi ou non, ainsi que le JSON ou le XML résultant, 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 un texte inséré, à utiliser avec d’autres tâches dans votre flux de travail, comme une tâche de code. Si vous avez testé votre service web, il se peut que vous ayez automatiquement des valeurs ici, car Qualtrics les extraira automatiquement des résultats.
    Astuce : Cliquez sur Ajouter un chemin personnalisé pour ajouter des chemins supplémentaires, ou cliquez sur la corbeille située à côté d’un chemin pour le supprimer.
23. Lorsque vous avez terminé la configuration de votre flux de travail, cliquez sur Enregistrer.

Ajout de justificatifs d’autorisation

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

Basique

L’authentificateur de base vous demande de vous connecter avec le nom d’utilisateur et le mot de passe de votre compte.

1. Donnez un nom à vos références. Il s’agit uniquement d’un outil d’organisation.
2. Choisissez Basic comme type de connexion.
3. Saisissez le nom d’utilisateur requis pour l’authentificateur.
4. Saisissez le mot de passe pour l’authentificateur.
5. Cliquez sur Connecter le compte.

Clé API

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

1. Donnez un nom à votre compte. Il s’agit uniquement d’un outil d’organisation.
2. Choisissez la clé API comme type de connexion.
3. Saisissez le clé API utilisé pour l’authentificateur.
4. Cliquez sur Connecter le compte.

OAuth 2.0

L’autorisation OAuth2.0 supprime la nécessité d’utiliser des clés API statiques ou un nom d’utilisateur et un mot de passe de base pour s’intégrer à 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 informations d’identification du client.

Vous pouvez utiliser l’autorisation OAuth 2.0 pour vous intégrer de manière transparente à de nombreuses plateformes tierces. La mise en œuvre du service web de Qualtrics suit la spécification officielle OAuth. Cependant, certains systèmes externes peuvent avoir des configurations légèrement différentes entraînant des incompatibilités avec l’autorisation OAuth2.0 dans la tâche du service web.

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

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

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

1. Donnez un nom à votre compte. Il s’agit uniquement d’un outil d’organisation.
2. Choisissez OAuth comme type de connexion.
3. Choisissez votre type de subvention, ou la façon dont le jeton d’accès est récupéré. Vous pouvez choisir :
   • Code d’autorisation
   • Identifiants client
4. Saisissez l’identifiant et le secret du client.
5. Saisissez le point d’extrémité du jeton.
6. Si vous avez sélectionné le code d’autorisation comme type de subvention, entrez le point final d’autorisation.
7. Cliquez sur Connecter le compte.

Renommer &amp ; Supprimer les informations d’identification

Pour modifier le nom de votre justificatif, cliquez sur les trois points situés à côté du compte. Pour supprimer les informations d’identification, cliquez sur Supprimer le compte.

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

Lorsque vous utilisez l’API Qualtrics, vous devez inclure votre clé API en tant qu’en-tête dans votre service web.

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

TLS mutuel

Mutual transport layer security (mTLS) est une couche de sécurité supplémentaire et facultative qui vient s’ajouter aux mécanismes d’authentification d’API standard (tels que le Clé api ou OAuth). TLS mutuel garantit que la personne qui se connecte à une API / un service web et l’API / le service web lui-même disposent d’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 correct pour que les demandes aboutissent. Si un appelant fait une demande en utilisant un certificat client invalide ou manquant, l’API qu’il essaie d’appeler bloquera la demande.

Conditions

La technologie de mTLS et le(s) format(s) de transmission des informations clés varient d’un service à l’autre. La prise en charge de mTLS n’est garantie que pour les services qui correspondent à nos exigences :

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

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

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

Ajout de mTLS

1. Créez votre tâche de service web.
   
2. Sélectionnez Authentificateur.
   
3. Cliquez sur Suivant.
4. Ajouter un compte d’utilisateur.
   
   Astuce : Un administrateur de l’organisation peut se connecter à un compte en utilisant la page Extensions.
   
5. Sélectionnez un type de connexion et remplissez vos informations d’identification.
   
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 : Si votre clé est dans un format différent, vous pouvez utiliser un autre programme pour modifier ce format.
   Astuce : Si vous envisagez d’utiliser l’API Qualtrics avec votre service web, consultez notre documentation API sur mTLS. Cette documentation vous montrera comment obtenir la clé privée. Lorsque vous collez la valeur dans Qualtrics, vous devez inclure des tirets indiquant “début de la clé privée” et “fin de la clé privée”
8. La clé publique est le certificat mTLS. Cette valeur doit être au format X.509.
   Astuce : Si vous prévoyez d’utiliser l’API Qualtrics avec votre service web, consultez notre documentation API sur mTLS. Cette documentation vous montrera comment retirer le certificat. Lorsque vous collez la valeur dans Qualtrics, vous devrez inclure des tirets indiquant “début du certificat” et “fin du certificat”
9. Lorsque vous avez terminé, cliquez sur Connecter le compte.
10. Procédez à l’installation de votre service web.

Utilisation des commandes Curl

Les commandes Curl sont l’une des nombreuses façons d’effectuer des requêtes HTTP, et constituent un outil précieux pour transmettre des informations dans les deux sens par le biais d’URL. Vous pouvez importer une commande curl pendant que vous configurez votre tâche pour remplir automatiquement différentes configurations de services web.

De nombreux Docs d’API fournissent souvent des exemples de curl que vous pouvez utiliser. La possibilité de copier et d’importer ces commandes peut donc faciliter et accélérer la mise en place des services web.

Pour des exemples de requêtes curl, regardez à droite sur chacun de ces Docs API :

• Obtenir une liste de distribution
• Créer une distribution de rappels
• Mise à jour de la Transaction du Contact
• Liste des utilisateurs dans le 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 celle-ci, nous fournirons quelques paramètres communs.

Paramètres de commande Curl pris en charge

Voici quelques-uns des paramètres curl supportés par la tâche de service web Qualtrics :

Paramètres d’en-tête communs

Nous avons mentionné plus haut que vous pouvez utiliser les commandes curl pour définir les en-têtes. Les en-têtes remplissent diverses fonctions dans la communication HTTP, telles que la fourniture d’informations sur la requête et le contrôle de l’authentificateur. 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

Tous les paramètres curl non listés ci-dessus ne sont pas pris en charge. Voici quelques exemples de formats de commandes curl que les tâches du service web Qualtrics ne prennent pas en charge :

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

Importer des commandes Curl

1. Pendant la configuration de votre tâche de service web, cliquez sur Import cURL.
   
2. Collez votre commande curl dans la boîte.
   
   Attention: Veillez à inclure votre méthode HTTP dans votre requête curl, surtout si vous copiez une commande curl provenant d’une autre plateforme.
   Astuce : Soyez attentif aux parties de la demande que vous devez remplir avec vos propres informations. Par exemple, dans la capture d’écran ci-dessus, vous remplaceriez “API Key” par votre clé API.

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

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

3. Cliquez sur Importer.
4. Les champs du service web seront remplis automatiquement.

FAQ