Plantilla de artículo

Acerca de la Tarea de servicio web

La tarea de Servicio web es útil si tiene experiencia con API y desea activador diferentes flujos de trabajo dentro del software Qualtrics , o en un servicio web externo, cuando el encuestado finaliza la encuesta. Por ejemplo, si su encuesta recopila la información de contacto del encuestado, entonces una tarea de servicio web puede usarla crear contacto Llamada API para agregar al encuestado a una lista de contactos.

También recomendamos visitar estas páginas relacionadas con servicios web para obtener más ayuda e información:

• 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

Dependiendo de cómo prefieras formatear los parámetros de tu cuerpo, la configuración variará ligeramente. Si está utilizando el formato JSON o XML , ingrese su cuerpo en el Cuerpo sección. Si prefiere una URL codificada, puede agregar parámetros como cadena de consulta hacia URL campo.

1. Crear un flujo de trabajo (o seleccionar uno existente) En tu proyecto o en el Página de Flujos de trabajo independientes .
   
2. Asegúrate de estar en el Sus flujos de trabajo sección.
3. Hacer clic Crear un flujo de trabajo.
4. Determinar el cronograma o el evento que desencadena tu tarea. ( Ver una comparación .)
5. Hacer clic Agregar tarea y seleccione Servicio Web .
   
6. Elija su método de autenticación. Sus opciones incluyen las siguientes:
   
   • Autenticado :Realizar 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 :Realizar una solicitud de servicio web sin autenticación.
7. Haga clic en Siguiente.
8. Si seleccionó una solicitud autenticada, seleccione sus credenciales de autorización de la lista o haga clic en Agregar Cuenta de usuario para agregar nuevas credenciales. Ver Agregar credenciales de autorización Para más información.
   
   Consejo Q: Podrás seleccionar cualquier credencial que hayas agregado previamente o credenciales agregadas por un administrador de Marca/organización en el Extensiones pestaña.
9. Hacer clic Siguiente.
10. Si tiene una solicitud con formato curl, puede importarla para configurar automáticamente su servicio web. Ver el Uso de comandos Curl Sección para más detalles.
    
11. Si lo desea, agregue un Resumen de la Tarea en la cima de su tarea. Esta es una descripción que explica el objetivo de la tarea.
12. Elige tu servicio web Pedido método. Ver Métodos de servicios web para obtener más información sobre cada método.
    
    Consejo Q : Si está utilizando la API de Qualtrics , La documentación Le indicará qué tipo de solicitud utilizar.
    Atención: Las tareas de WebService no permiten ninguna redirección de URL para solicitudes que no sean GET. Solo se permite una redirección para solicitudes GET.
13. Introduzca la URL de su solicitud.
    Consejo Q: Puede limitar los dominios a los que la tarea del servicio web puede conectarse especificando los dominios en su configuración del dominio de extensión .
14. Si lo desea, haga clic en Agregar encabezado para agregar un encabezado. Especificar el Llave y Valor. Para eliminar un encabezado, haga clic en el ícono de la papelera siguiente al encabezado.
    Consejo Q: Utilice el icono de texto dinámico , {a} , para insertar texto dinámico para extraer valores de las respuestas de la encuesta o de tareas anteriores en el flujo de trabajo.
    Atención: Si utiliza la API de Qualtrics , debe incluir su token de API a través del encabezado. Ver Cómo agregar un encabezado para las solicitudes de API de Qualtrics Para más información.
15. Si elige publicar, colocar o parchear, deberá elegir el formato de su cuerpo. Las opciones incluyen JSON , URL codificada , XML , y Texto sin formato.
    
    
16. Determina cómo quieres especificar el cuerpo de tu solicitud. Puedes agregar el cuerpo como Pares clave-valor o Texto libre .
17. Si seleccionó pares clave-valor, agregue el Llave y sus asociados Valor . Hacer clic Agregar par clave-valor para agregar parámetros adicionales.
    Atención: Para CORREO , PONER , y PARCHE solicita que especifique un tipo de datos para cada par clave-valor.
18. Seleccione una Tipo de datos.
    • Booleano: Seleccione este tipo de datos si sus datos tienen uno de 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.
    • Predeterminado del sistema: Seleccione este tipo de datos si desea utilizar el tipo de datos nativo para sus datos. Si no se puede encontrar un tipo de datos, el valor predeterminado será Cadena tipo.
      Consejo Q: Le recomendamos seleccionar uno de los otros tipos de datos para garantizar que sus datos se conviertan correctamente.
      Atención: Los pares clave-valor que se configuraron antes del 16 de septiembre de 2022 tendrán un tipo de datos de Predeterminado del sistema .
    Consejo Q: El Tipo de datos El campo solo está disponible cuando seleccionas JSON y Pares clave-valor en los pasos 13-14.
19. Seleccione qué sucede si no se puede convertir el tipo de datos.
    • No convierta un tipo de datos y marque como error: Si no se puede convertir el tipo de datos, no se convertirá ningún tipo de datos y la tarea fallará. Esto se puede ver en el Historial de ejecución pestaña.
    • Convierte el tipo de datos al valor predeterminado del sistema: Si no se puede convertir el tipo de datos, el tipo de datos se establecerá en Predeterminado del sistema .
20. Si seleccionó Texto libre, ingrese 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 en absoluto o ingrese el término “nulo” para indicar valores vacíos. Recomendamos excluir el campo.
    Consejo Q: Si una tarea de servicio web encuentra un cuerpo JSON no válido, la tarea no fallará. En su lugar, el JSON no válido se convertirá en una cadena y se guardará como una propiedad “texto” en un nuevo objeto JSON . De esta manera, podrás ver el texto no válido una vez que la tarea termine de procesarse.
    Atención: Las tareas del servicio web actualmente no admiten comentarios.
21. Para probar su servicio web, haga clic en Ejecutar prueba .
    
    Consejo Q: Después de hacer clic en Ejecutar prueba, aparecerá el resultado de su solicitud, permitiéndole saber si fue exitosa o no, y el JSON o XML resultante, si fue exitosa.
22. Hacer clic Agregar ruta personalizada para agregar rutas JSON o XML . Estas rutas le permiten utilizar los resultados de su servicio web en texto dinámico, para usarlos con otras tareas en su flujo de trabajo, como por ejemplo: tarea de código . Si probó su servicio web, es posible que tenga valores automáticamente aquí, ya que Qualtrics los extraerá automáticamente de los resultados.
    Consejo Q: Hacer clic Agregar ruta personalizada para agregar rutas adicionales, o haga clic en la papelera siguiente a una ruta para eliminarla.
23. Cuando termine de configurar su flujo de trabajo, haga clic en Ahorrar .

Agregar credenciales de autorización

Esta sección cubre cómo agregar credenciales de autorización para la tarea de servicio web. Puede agregar credenciales utilizando el Básico, Clave API , o OAuth 2.0 método. Para agregar credenciales, haga clic en Agregar cuenta de usuario desde la ventana de selección de credenciales.

Básico

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

1. Dale un toque a tus credenciales Nombre . Esto es sólo para fines organizativos.
2. Elegir Básico como el tipo de conexión.
3. Entrar en el Nombre de usuario requerido para la autenticación.
4. Entrar en el Contraseña para autenticación.
5. Hacer clic Conectar cuenta .

Clave de API

La autenticación mediante clave API le permite autenticarse utilizando un token de API estático.

1. Dale un toque a tu cuenta Nombre . Esto es sólo para fines organizativos.
2. Elegir Clave API como el tipo de conexión.
3. Entrar en el Token de API utilizado para autenticación.
4. Hacer clic Conectar cuenta .

OAuth 2.0

La autorización OAuth2.0 elimina la necesidad de utilizar tokens de API estáticos o nombres de usuario y contraseñas básicos para integrarse 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 perfectamente 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, lo que genera incompatibilidades con la autorización OAuth2.0 en la tarea del servicio web.

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

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

Para autenticarse usando OAuth 2.0:

1. Dale un toque a tu cuenta Nombre . Esto es sólo para sus propios fines organizativos.
2. Elegir OAuth como el tipo de conexión.
3. Elige tu Tipo de subvención , o cómo se recupera el token de acceso. Usted puede elegir:
   • Código de autorización
   • Credenciales del cliente
4. Entrar en el Identificación del cliente y Secreto del cliente .
5. Entrar en el Punto final del token .
6. Si seleccionó el código de autorización como tipo de concesión, ingrese el Punto final de autorización .
7. Hacer clic Conectar cuenta .

Cambiar el nombre y eliminar credenciales

Para editar el nombre de sus credenciales, haga clic en los tres puntos siguiente a la cuenta. Para eliminar credenciales, haga clic en Eliminar cuenta .

Cómo agregar un encabezado para las solicitudes de API de Qualtrics

Al utilizar el API de Qualtrics , usted debe incluir su token de API como encabezado en su servicio web.

1. Configuración su tarea de servicio web, seleccione sus credenciales y elija su solicitud.
   
2. En la sección Encabezados, ingrese X- API-TOKEN como la clave.
3. Para el valor, haga clic en el ícono de texto dinámico , {a} .
4. Seleccione sus credenciales de la lista.
   

TLS mutuo

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

Requisitos

Cada servicio varía en cuanto a si admite mTLS y en qué formatos proporciona información clave. Solo garantizamos compatibilidad con mTLS para servicios que coincidan con nuestros requisitos:

• Proporcionar 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 arriba.

mTLS solo es compatible con Autenticado servicios web creados en flujos de trabajo . Se admiten los tres métodos de autenticación (básico, clave API y OAuth2.0).

Añadiendo mTLS

1. Crea tu tarea de servicio web .
   
2. Elegir Autenticado .
   
3. Haga clic en Siguiente.
4. Añadir una cuenta de usuario.
   
   Consejo Q: A Administrador de Marca/organización puede conectarse a una cuenta usando el Extensiones página.
   
5. Seleccione una tipo de conexión y complete sus credenciales.
   
6. Seleccionar Habilitar mTLS .
7. El Clave privada Puede considerarse como el identificador único del cliente que intenta conectarse. Este valor debe estar en formato PKCS8.
   Consejo Q: Si su clave está en un formato diferente, puede utilizar otro programa para cambiar este formato.
   Consejo Q : Si planea utilizar la API de Qualtrics con su servicio web, consulte Nuestra documentación API sobre mTLS . Esta documentación le mostrará cómo extraer la clave privada. Cuando pegue el valor en Qualtrics, deberá incluir guiones que digan “inicio de clave privada” y “fin de clave privada”.
8. El Clave pública es el certificado mTLS . Este valor debe estar en formato X.509.
   Consejo Q : Si planea utilizar la API de Qualtrics con su servicio web, consulte Nuestra documentación API sobre mTLS . Esta documentación le mostrará cómo obtener el certificado. Cuando pegue el valor en Qualtrics, deberá incluir guiones que digan “inicio del certificado” y “fin del certificado”.
9. Cuando haya terminado, haga clic en Conectar Cuenta .
10. Continúe con la configuración de su servicio web .

Uso de comandos Curl

Los comandos curl son una de las muchas maneras en que puedes realizar solicitudes HTTP y son una herramienta valiosa para pasar información de un lado a otro a través de URL. Puedes importar un comando curl mientras configuras tu tarea para completar automáticamente diferentes configuraciones de servicios web.

Muchos documentos de API suelen proporcionar ejemplos de curl que puedes usar. Poder copiar e importar estos comandos puede hacer que la configuración del servicio web sea mucho más rápida y sencilla.

Para ver algunos ejemplos de solicitudes curl, mira a la derecha de cada uno de estos documentos de API :

• Obtener Lista de correo
• Crear Distribución de Recordatorio
• Actualizar Transacción de Contacto
• Lista de usuarios en el grupo

Para una solicitud GET, el comando curl puede ser tan simple como curl https:// api.example.com/parameters . Para los comandos curl que no son tan simples como este, proporcionaremos algunos parámetros comunes.

Parámetros del comando Curl admitidos

Estos son algunos de los parámetros curl que admite la tarea del servicio web de Qualtrics :

Parámetros de encabezado comunes

Arriba, mencionamos que puedes usar comandos curl para definir encabezados. Los encabezados cumplen diversos propósitos en la comunicación HTTP, como proporcionar información sobre la solicitud y controlar la autenticación. Los encabezados específicos que utilice dependerán de los requisitos de la aplicación o API que esté utilizando.

A continuación se muestran algunos ejemplos de parámetros de encabezado:

Parámetros no admitidos

Cualquier parámetro de rizo no enumerado anteriormente es no apoyado. A continuación se muestran algunos ejemplos de formatos de comando curl que las tareas del servicio web de Qualtrics no admiten:

• --galleta para enviar cookies con la solicitud.
• --El o --ubicación para seguir redirecciones.
• --tiempo máximo para establecer el tiempo máximo de solicitud.
• --o o --producción para guardar la respuesta en un archivo.
• --inseguro permitir conexiones inseguras.
• --A o --agente de usuario para especificar el agente de usuario.

Importación de comandos Curl

1. Durante la configuración de la tarea del servicio web, haga clic en Importar cURL .
   
2. Pegue su comando curl en el cuadro.
   
   Atención :Asegúrese de incluir su método HTTP en su solicitud curl, especialmente si está copiando un comando curl de otra plataforma.
   Consejo Q: Esté atento a las partes de la solicitud que deberá completar con su propia información. Por ejemplo, en la captura de pantalla anterior, reemplazaría “Clave API ” con su token de API .

   Consejo Q: Puede agregar un comando en una sola cadena o puede marcar saltos de línea utilizando el carácter de escape ( \ ). Nosotros lo hacemos no admite otros escapes de línea (por ejemplo, ^ ). A continuación se muestra un ejemplo de un comando curl con caracteres de escape admitidos:

   rizo https://www.google.com/accounts/test \
    -d tipoCuenta=GOOGLE \
    -d source=Ejemplo-cURL-Google \
    -d servicio=lh2

3. Haga clic en Importar.
4. Los campos del servicio web se completarán automáticamente.

Preguntas frecuentes