Tâche du service Web
Contenus de cette page
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é
Astuce: Cette page contient des références à l’API de Qualtrics, une fonction dont l’accès nécessite une autorisation spéciale. Si vous souhaitez obtenir l’accès à cette fonction, veuillez contacter votre Administrateur de l’Organisation pour plus d’informations.
Attention: La mise en place d’un service web nécessite souvent des connaissances avancées en programmation. Bien que notre équipe d’assistance soit heureuse de vous aider à introduire des informations dans le service web, nous ne sommes pas en mesure de vous aider pour les aspects liés à la programmation.
Attention: Les tâches de service web ne prennent en charge que les types de contenu suivants : URL-Encoded, XML, JSON, et Plain Text.
Astuce: Configurez-vous votre service web à partir d’une documentation sur l’API ? Votre installation peut être beaucoup plus rapide si vous importez une commande curl.
Configuration d’une tâche de service web
Attention : La sortie de l’appel effectué dans votre tâche de service Web est limitée à 1 Mo.
Astuce: vous pouvez utiliser l’assistant IA pour vous aider à configurer la tâche de service web. Pour plus d’informations, voir Utilisation de l’assistance AI pour la configuration des tâches.
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.
- 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.
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.
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.
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.
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.
Astuce : Le nombre maximal de caractères pour les paires clé-valeur et le texte libre est de 75 000.
Attention : Pour les requêtes POST, PUT et PATCH, vous devez spécifier un type de données pour chaque paire clé-valeur.
- 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. Astuce: Assurez-vous que les données saisies sont des JSON valides. Lors de l’utilisation d’un texte inséré, veillez à ce que les caractères spéciaux ne soient pas inclus.
- 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.
- 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.
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.
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.
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.
Attention : Les données d’une tâche qui a échoué ne peuvent pas être transférées dans une autre tâche. Le texte inséré s’affichera sous la forme d’une valeur nulle.
Astuce : Les tâches des services web ont un délai d’attente de 16 secondes. Si un appel au service web prend plus de 10 secondes, le flux de travail échouera.
Utilisation de l’assistant d’intelligence artificielle pour la mise en place des tâches
Attention : Vous ne pouvez utiliser le mappage automatique que si un Administrateur de l’Organisation a activé l’autorisation Assistance AI dans la configuration des flux de travail pour votre organisation dans l’onglet Administration.
L’assistant AI peut configurer l’intégration de l’API dans les tâches de service web en lisant la documentation de l’API disponible publiquement et en configurant la tâche automatiquement.
Astuce: si l’assistant AI ne parvient pas à générer un brouillon, modifiez la demande et réessayez.
Astuce: Bien que nous ayons mis en place des garde-fous et que nous perfectionnions continuellement nos produits, l’intelligence artificielle peut parfois générer des résultats inexacts, incomplets ou obsolètes. Avant d’utiliser les résultats des fonctions d’IA de Qualtrics, vous devez vérifier l’exactitude des résultats et vous assurer qu’ils sont adaptés à votre cas d’utilisation. Les résultats fournis par les fonctions d’IA de Qualtrics ne remplacent pas un examen par un être humain ou des conseils de professionnels.
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.
Astuce : Tous les types de connexion sont compatibles avec mTLS. Pour en savoir plus, voir la section TLS mutuel.
Basique
L’authentificateur de base vous demande de vous connecter avec le nom d’utilisateur et le mot de passe de votre compte.
Clé API
L’authentification par clé API vous permet de vous authentifier à l’aide d’un clé API statique.
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.
Astuce: lors de la création d’une connexion OAuth, l’URL de redirection serahttps://{dataCenter}.qualtrics.com/oauth-client-service/redirect, où {dataCenter} représente la valeur associée à votre compte. Consultez cette page pour plus de détails sur la façon de trouver le centre de données de votre compte.
Pour s’authentifier à l’aide d’OAuth 2.0 :
Astuce : Pour les utilisateurs qui configurent les informations d’identification Google OAuth, incluez le paramètre suivant à la fin de votre Token Endpoint : “?prompt=consent.” Si vous disposez de paramètres de requête existants, le point d’interrogation n’est pas nécessaire.
Astuce : Si vous avez des difficultés à vous connecter avec Snowflake, assurez-vous que les plages d’IP de Qualtrics sont autorisées.
Renommer & ; 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.
Astuce : vous ne pouvez renommer ou supprimer que les informations d’identification que vous avez vous-même ajoutées.
Attention : Soyez prudent lorsque vous supprimez des informations d’identification ! Tous les flux de travail qui utilisent les informations d’identification cesseront de fonctionner lorsque les informations d’identification seront supprimées.
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.
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
Astuce : Un administrateur de l’organisation peut se connecter à un compte en utilisant la page Extensions.
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”
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”
Astuce : La validité de vos clés mTLS ne peut pas être testée tant que vous n’exécutez pas un appel API via votre service web. Vous ne verrez donc pas de message d’erreur sur cette page si vous avez saisi vos clés de manière incorrecte. Testez le service web avant de mettre votre flux de travail en ligne.
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.
Astuce : Si vous modifiez une tâche de service web existante, toutes les commandes curl que vous importez écraseront les configurations précédentes.
Astuce : Si vous souhaitez en savoir plus sur curl que ce que nous abordons ci-dessous, nous vous recommandons de lire une ressource en dehors du support de Qualtrics, comme la documentation d’IBM.
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 | Description | Commande Curl | Exemple |
|---|---|---|---|
| URL | Le point de terminaison ou la ressource avec laquelle le service web doit interagir. | URL complet. | https://datacenter.qualtrics.com/API/v3/directories/ |
| Méthode HTTP | Des options telles que GET, POST, PUT, etc. | --X <command> ou --request <command> | Exemple 1 : --X GET Exemple 2 : --request PUT |
| En-têtes | Collecteurs personnalisés. | --H ou --header | Exemple 1 : --header 'Accept: application/json' Exemple 2 : --header 'Content-Type: application/json' |
| Corps | Le corps (ou charge utile) des requêtes POST. | --d ou --data | --data '{ “description” : “Liste de tous les bogues ouverts”, “jql” : “type = Bug et résolution vide”, “name” : “Tous les bogues ouverts” }’ |
| Format JSON | Remplacer le fait de devoir spécifier le formatage JSON dans l’en-tête et les données. | --json | Cette commande curl remplace les 3 balises suivantes :   ; --data [arg] --header "Content-Type: application/json" --header "Accept: application/json" |
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 :
| Nom | Description | Exemple |
|---|---|---|
| Accepter | Spécifiez les formats de support pour la réponse. | Accept: application/json |
| Type de contenu | Dans une requête, le type de contenu spécifie le type de média de la ressource envoyée au serveur. Dans la réponse, le type de contenu indique le type de média de la ressource contenue dans le corps du message. | Content-Type: application/json |
| Autorisation | Fournir des informations d’identification pour accéder à une ressource protégée. | Authorization: Bearer token |
| ETag | Fournir un identifiant unique pour une version spécifique d’une ressource. | ETag: "123456" |
| Longueur du contenu | Définir la taille du corps de l’entité dans le message. | Content-Length: 1024 |
| Origine | Indiquer l’origine de la demande. Cela peut faciliter le partage des ressources entre origines (CORS). | Origin: https://example.com |
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 demande.
- --L ou --location pour les redirections suivantes.
- --max-time pour définir le temps de requête maximum.
- --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.
Astuce : Si vous essayez d’importer une commande curl avec des paramètres non pris en charge, un message d’erreur s’affiche, listant les paramètres non pris en charge que vous avez utilisés. Vous aurez la possibilité de continuer à importer votre commande curl en supprimant les paramètres non pris en charge.
Importer des commandes Curl
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
Astuce : Nous vous recommandons de vérifier vos champs avant d’activer votre flux de travail.
FAQs
Ai-je accès à toutes les extensions disponibles via les modèles de workflows ?
Ai-je accès à toutes les extensions disponibles via les modèles de workflows ?
Existe-t-il un lien vers tous les déclencheurs d'événements, flux de contrôle et tâches des workflows ?
Existe-t-il un lien vers tous les déclencheurs d'événements, flux de contrôle et tâches des workflows ?
Qu'est-ce qu'un modèle de workflow ?
Qu'est-ce qu'un modèle de workflow ?
Qu'est-ce qu'un flux de travail ? / Où sont les actions ?
Qu'est-ce qu'un flux de travail ? / Où sont les actions ?
Aucune modification n’a été apportée à la fonctionnalité de workflow dans le cadre de cette mise à jour.
C'est génial! Merci pour votre avis!
Merci pour votre avis!
Comment ajouter ou supprimer une extension de mon compte Qualtrics ?