Tarea de servicio web

Acerca de la tarea de servicio web

The Web Service task is useful if you are experienced with API and would like to trigger different workflows within the Qualtrics software, or to an external web service, when the respondent finishes the survey. Por ejemplo, si su encuesta recopila la información de contacto del encuestado, una tarea de servicio web puede utilizar la llamada a la API Crear contacto para añadir el encuestado a una lista de contactos.

También recomendamos visitar estas páginas relacionadas con el servicio web para obtener más ayuda y antecedentes:

• Centro de desarrolladores de Qualtrics
• Métodos de servicio web
• Documentación API
• Pasar información mediante cadenas de consulta
• Texto dinámico

Configuración de una tarea de servicio web

En función de cómo prefiera dar formato a los parámetros del cuerpo, la configuración variará ligeramente. Si utiliza el formato JSON o XML, introduzca el cuerpo en la sección Cuerpo. Si prefiere una codificación URL, puede añadir parámetros como cadena de consulta al campo URL.

1. Cree un flujo de trabajo (o seleccione uno existente) en su proyecto o en la página Flujos de trabajo independientes.
   
2. Asegúrese de que se encuentra en la sección Sus workflows.
3. Haga clic en Crear un flujo de trabajo.
4. Determine la programación o el evento que desencadena la tarea. (Ver una comparación.)
5. Haga clic en Añadir tarea y seleccione Servicio web.
   
6. Seleccione su método de autenticación. Sus opciones incluyen:
   
   • Autenticado: Realice una solicitud de servicio web autenticada. Sus opciones de autenticación incluyen básica (con contraseña y nombre de usuario), clave API y OAuth.
   • No autenticado: Realice una solicitud de servicio web sin autenticación.
7. Haga clic en Siguiente.
8. Si ha seleccionado una solicitud autenticada, seleccione sus credenciales de autorización de la lista o haga clic en Añadir cuenta de usuario para añadir credenciales nuevas. Consulte Añadir credenciales de autorización para obtener más información.
   
   Consejo Q: Podrá seleccionar las credenciales que haya añadido previamente o las que haya añadido un administrador de organización en la pestaña Extensiones.
9. Haga clic en Siguiente.
10. If you’ve got a curl-formatted request, you can import it to automatically set your web service up. See the Using Curl Commands section for details.
    
11. Si lo desea, añada un resumen de tarea en la parte superior de su tarea. Esta es una descripción que explica el objetivo de la tarea.
12. Seleccione el método de solicitud de su servicio web. Consulte Métodos de servicio web para obtener más información sobre cada método.
    
    Consejo Q: Si utiliza la API de Qualtrics, la documentación le indicará qué tipo de solicitud utilizar.
    Atención: Las tareas de servicio web no permiten redireccionamientos de URL para solicitudes que no sean GET. Solo se permite un redireccionamiento para solicitudes GET.
13. Introduzca la URL para su solicitud.
    Consejo Q: Puede limitar los dominios a los que se puede conectar la tarea de servicio web especificando los dominios en las opciones del dominio de extensión.
14. Si lo desea, haga clic en Añadir cabecera para añadir una cabecera. Especifique la clave y el valor. Para eliminar una cabecera, haga clic en el icono de papelera junto a la cabecera.
    Consejo Q: Utilice el icono de texto dinámico, {a}, para insertar texto dinámico para obtener valores de respuestas de encuesta o tareas anteriores en el flujo de trabajo.
    Atención: Si utiliza la API de Qualtrics, debe incluir su token de API a través de la cabecera. Consulte Añadir un encabezado para solicitudes de API de Qualtrics para obtener más información.
    Atención: Para solicitudes POST, PUT y PATCH debe especificar un tipo de datos para cada par clave-valor.
    Atención: Actualmente, las tareas de servicio web no admiten comentarios/texto en el cuerpo que contiene secuencias de escape.
15. Si eliges postear, poner o parche, tendrás que elegir el formato de tu cuerpo. Las opciones incluyen JSON, codificado con URL, XML y Texto sin formato.
    
    
    Consejo Q: El texto sin formato solo se puede especificar como texto libre. Al utilizar la opción de texto libre JSON, las entradas no se escaparán. Esto significa que, por ejemplo, una entrada de texto dinámico que contenga comillas dobles o caracteres de nueva línea (ejemplo: \n) hará que el cuerpo JSON no sea válido y no se ejecute correctamente. Una alternativa a esto es utilizar la opción de pares clave-valor o utilizar una tarea de código para limpiar o escapar del texto que se va a inyectar en la tarea de servicio web.
16. Determine cómo desea especificar el cuerpo de su solicitud. Puede añadir el cuerpo como pares de valores clave o texto libre.
17. Si ha seleccionado pares clave-valor, añada la clave y su valor asociado. Haga clic en Añadir par clave-valor para añadir parámetros adicionales.
18. Seleccione un tipo de datos.
    • Booleano: Seleccione este tipo de datos si sus datos tienen uno de los dos valores posibles.
    • JSON: Seleccione este tipo de datos si sus datos están en formato JSON.
    • Número: Seleccione este tipo de datos si sus datos son numéricos.
    • Cadena: Seleccione este tipo de datos si sus datos están en formato de texto.
    • Valor predeterminado del sistema: seleccione este tipo de datos si desea utilizar el tipo de datos nativo para sus datos. Si no se encuentra un tipo de datos, se utilizará de forma predeterminada el tipo Cadena.
      Consejo Q: Recomendamos seleccionar uno de los otros tipos de datos para asegurarse de que los datos se emiten correctamente.
      Atención: Los pares clave-valor que se configuraron antes del 16 de septiembre de 2022 tendrán un tipo de datos Estándar de sistema.
    Consejo Q: El campo Tipo de datos solo está disponible si selecciona pares JSON y Valor-Clave en los pasos 13-14.
19. Seleccione lo que sucede si el tipo de datos no se puede convertir.
    • No indique un tipo de datos y márquelo como error: Si el tipo de datos no se puede convertir, no se creará ningún tipo de datos y la tarea fallará. Esto se puede ver en la pestaña Historial de ejecución.
    • Cast el tipo de datos al predeterminado del sistema: Si no se puede emitir el tipo de datos, el tipo de datos se fijará en Valor predeterminado del sistema.
20. Si ha seleccionado Texto libre, introduzca los parámetros del cuerpo en el formato seleccionado.
    
    Atención: No debe dejar este campo vacío ni tener claves sin valores. En su lugar, no incluya el campo o introduzca el término “nulo” para indicar valores vacíos. Recomendamos excluir el campo.
21. Para probar el servicio web, haga clic en Ejecutar prueba.
    
    Consejo Q: Después de hacer clic en Ejecutar prueba, aparecerá el resultado de su solicitud, que le indicará si se ha realizado correctamente o no, y el JSON o XML resultante, si se ha realizado correctamente.
22. Haga clic en Añadir vía de acceso personalizada para añadir vías de acceso JSON o XML. Estas rutas le permiten utilizar los resultados de su servicio web en texto dinámico, para utilizarlos con otras tareas de su flujo de trabajo, como una tarea de código. Si probó su servicio web, puede tener valores automáticamente aquí, ya que Qualtrics los extraerá automáticamente de los resultados.
    Consejo Q: Haga clic en Añadir vía de acceso personalizada para añadir vías de acceso adicionales o haga clic en la papelera junto a una vía de acceso para borrarla.
23. Cuando termine de configurar su workflow, haga clic en Guardar.

Añadir credenciales de autorización

En esta sección se explica cómo añadir credenciales de autorización para la tarea de servicio web. Puede añadir credenciales con el método básico, clave API o OAuth 2.0. Para añadir credenciales, haga clic en Añadir cuenta de usuario en la ventana de selección de credenciales.

Básico

La autenticación básica requiere que inicie sesión con el nombre de usuario y la contraseña de su cuenta.

1. Asigne un nombre a sus credenciales. Esto es solo para fines organizativos.
2. Seleccione Básico como el tipo de conexión.
3. Introduzca el nombre de usuario necesario para la autenticación.
4. Introduzca la contraseña para la autenticación.
5. Haga clic en Conectar cuenta.

Clave de API

La autenticación de clave API le permite autenticarse mediante un indicativo de API estática.

1. Asigne un nombre a su cuenta. Esto es solo para fines organizativos.
2. Seleccione la clave API como el tipo de conexión.
3. Introduzca el token de API utilizado para la autenticación.
4. Haga clic en Conectar cuenta.

OAuth 2.0

La autorización OAuth2.0 elimina la necesidad de utilizar tokens de API estáticos o nombre de usuario y contraseña básicos para la integración con plataformas de terceros. La tarea de servicio web admite dos tipos de autorización OAuth2.0 diferentes: código de autorización y credenciales de cliente.

Puede utilizar la autorización OAuth 2.0 para integrarse sin problemas con muchas plataformas de terceros. La implementación del servicio Web de Qualtrics sigue la especificación oficial de OAuth. Sin embargo, algunos sistemas externos pueden tener configuraciones ligeramente diferentes que provocan incompatibilidades con la autorización OAuth2.0 en la tarea de servicio web.

Las siguientes integraciones son algunos ejemplos que se han verificado completamente para trabajar con OAuth2.0:

• Salesforce utilizando el método de código de autorización.
• Jira utilizando el método de código de autorización.
• Zoom utilizando el método de código de autorización.

Para autenticarse con OAuth 2.0:

1. Asigne un nombre a su cuenta. Esto es solo para sus propios fines organizativos.
2. Seleccione OAuth como tipo de conexión.
3. Seleccione el tipo Conceder o cómo se recupera el token de acceso. Puede elegir:
   • Código de autorización
   • Credenciales del cliente
4. Introduzca el ID de cliente y el secreto de cliente.
5. Introduzca el punto final Token.
6. Si ha seleccionado el código de autorización como el tipo de concesión, introduzca el punto final Autorización.
7. Haga clic en Conectar cuenta.

&Renombrar; eliminando credenciales

Para editar el nombre de su credencial, haga clic en los tres puntos junto a la cuenta. Para eliminar credenciales, haga clic en Eliminar cuenta.

Añadir un encabezado para solicitudes de API de Qualtrics

Al usar la API de Qualtrics, debe incluir su token de API como encabezado en su servicio web.

1. Configure su tarea de servicio web, seleccione sus credenciales y elija su solicitud.
   
2. En la sección Cabeceras, introduzca X-API-TOKEN como Clave.
3. Para el valor, haga clic en el icono de texto dinámico, {a}.
4. Seleccione sus credenciales de la lista.
   

TLS mutuo

La seguridad de capa de transporte mutua (mTLS) es una capa adicional y opcional de seguridad sobre los mecanismos de autenticación API estándar (como token de API o OAuth). TLS mutuo garantiza que tanto la persona que se conecta a una API / servicio web y la API / servicio web en sí tienen tráfico seguro y cifrado en ambas direcciones. Una vez activado mTLS, todas las solicitudes deben presentar el certificado de cliente correcto para que las solicitudes tengan éxito. Si un autor de la llamada realiza una solicitud utilizando un certificado de cliente no válido o que falta, la API a la que intenta llamar bloqueará la solicitud.

Requisitos

Cada servicio varía en si admite mTLS y en qué formato proporciona información clave. Solo se nos garantiza el soporte de mTLS para servicios que cumplan con nuestros requisitos:

• Proporcione una clave privada
• La clave privada se puede formatear en PKCS8
• Proporcionar un certificado
• El certificado se puede formatear en X.509

Las API públicas de Qualtrics admiten mTLS como se describe anteriormente.

mTLS solo se admite para servicios web autenticados creados en flujos de trabajo. Se admiten los tres métodos de autenticación (Basic, API key y OAuth2.0).

Añadir mTLS

1. Cree su tarea de servicio Web.
   
2. Seleccione Autenticado.
   
3. Haga clic en Siguiente.
4. Añada una cuenta de usuario.
   
   Consejo Q: Un administrador de organización puede conectarse a una cuenta mediante la página Extensiones.
   
5. Seleccione un tipo de conexión y rellene sus credenciales.
   
6. Seleccione Activar mTLS.
7. La clave privada se puede pensar como el identificador único del cliente que intenta conectarse. Este valor debe estar en formato PKCS8.
   Consejo Q: Si su clave tiene un formato diferente, puede cambiarlo utilizando otro programa para cambiar este formato.
   Consejo Q: Si tiene previsto utilizar la API de Qualtrics con su servicio web, consulte nuestra Documentación de API en mTLS. Esta documentación le mostrará cómo obtener la clave privada. Cuando pegue el valor en Qualtrics, tendrá que incluir guiones que digan “comenzar clave privada” y “finalizar clave privada”.
8. La clave pública es el certificado mTLS. Este valor debe tener el formato X.509.
   Consejo Q: Si tiene previsto utilizar la API de Qualtrics con su servicio web, consulte nuestra Documentación de API en mTLS. Esta documentación le mostrará cómo extraer el certificado. Cuando pegue el valor en Qualtrics, tendrá que incluir guiones que digan “certificado de inicio” y “certificado final”.
9. Cuando haya terminado, haga clic en Conectar cuenta.
10. Continúe con la configuración del servicio Web.

Using Curl Commands

Curl commands are one of many ways you can make HTTP requests, and are a valuable tool in passing information back and forth through URLs. You can import a curl command while you’re setting up your task to auto-populate different web service configurations.

Many API docs often provide curl examples you can use. Being able to copy and import these commands can thus make web service setup much quicker and easier.

For some examples of curl requests, look at the right on each of these API docs:

• Get Mailing List
• Create Reminder Distribution
• Actualizar transacción de contacto
• List Users in Group

For a GET request, the curl command can be as simple as curl https://api.example.com/parameters. For curl commands that aren’t as simple as this, we’ll provide some common parameters.

Supported Curl Command Parameters

Here are some of the curl parameters the Qualtrics web service task supports:

Common Header Parameters

Above, we mentioned you can use curl commands to define headers. Headers serve various purposes in HTTP communication, such as providing information about the request and controlling authentication. The specific headers you use depend on the requirements of the application or API you’re using.

Here are some examples of header parameters:

Unsupported Parameters

Any curl parameters not listed above are not supported. Here are a few examples of curl command formats Qualtrics web service tasks do not support:

• --cookie to send cookies with the request.
• --L or --location for following redirects.
• --max-time for setting maximum request time.
• --o or --output for saving response to a file.
• --insecure to allow insecure connections.
• --A or --user-agent to specify user agent.

Importing Curl Commands

1. During your web service task setup, click Import cURL.
   
2. Paste your curl command in the box.
   
   Attention: Make sure you include your HTTP method in your curl request, especially if you’re copying a curl command from another platform.
   Qtip: Keep an eye out for parts of the request you need to fill out with your own information. For example, in the screenshot above, you’d replace “API Key” with your API token.

   Qtip: You can add a command in one single string, or you can mark line breaks using the escape character ( \ ). We do not support other line escapes (for example, ^ ). Here’s an example of a curl command with supported escape characters:

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

3. Haga clic en Importar.
4. Web service fields will be filled automatically.

Preguntas frecuentes