Tarea de servicio web

Acerca de la tarea de servicio web

La tarea de servicio web es útil si es experto en API y desea desencadenar diferentes flujos de trabajo dentro del software de Qualtrics, o a un servicio web externo, cuando el encuestado termina la encuesta. 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. 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.
    
11. 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.
12. 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.
13. Si lo desea, añada cabeceras a su solicitud escribiendo la cabecera Clave y valor. Las cabeceras llevan metadatos relacionados con la solicitud. Haga clic en Añadir cabecera para añadir cabeceras adicionales. Para eliminar un encabezado, haga clic en el icono de papelera junto al encabezado.
    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.
14. Si eliges post, put o patch, 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, no se escapan las entradas. 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 deje de ser válido y no se ejecute correctamente. Una alternativa a esto es usar la opción de pares clave-valor o usar una tarea de código para limpiar o escapar del texto que se va a inyectar en la tarea de servicio web.
15. Determine cómo desea especificar el cuerpo de su solicitud. Puede añadir el cuerpo como pares de valores clave o texto libre.
16. 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.
17. 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.
18. 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.
19. Si ha seleccionado Texto libre, introduzca los parámetros del cuerpo en el formato seleccionado.
    
20. 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, informándole de si se ha realizado correctamente o no, y del JSON o XML resultante, de si se ha realizado correctamente.
21. 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 del servicio Web en texto dinámico, para utilizarlos con otras tareas del 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.
22. 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.

Cambiar nombre de & eliminar 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 cabecera 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 es compatible con 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.

Preguntas frecuentes