Tarea de servicio web

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

Consejo Q: Esta página contiene referencias a la API de Qualtrics , que es una función que requiere un permiso especial para acceder. Si está interesado en obtener acceso a esta función, comuníquese con su Administrador de Marca/organización Para más información.

Atención: La configuración de un servicio web a menudo requiere conocimientos avanzados de programación. Si bien nuestro equipo de soporte estará encantado de ayudarle con los aspectos básicos de cómo introducir información en el servicio web, no podemos brindar asistencia en los aspectos de programación.

Atención: Las tareas de servicio web solo admiten los siguientes tipos de contenido: URL codificada, XML, JSON y texto sin formato.

Consejo Q: ¿Está configurando su servicio web desde un doc API ? Su configuración puede ser mucho más rápida si importar un comando curl .

Configuración de una Tarea de servicio web

Atención: La salida de la llamada que se realiza en su tarea de servicio web tiene un límite de 1 MB.

Consejo Q: Puede utilizar el Asistente de inteligencia artificial para ayudar a configurar la tarea del servicio web. Para obtener más información, consulte Uso de la asistencia de IA para la configuración de Tarea.

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.

Crear un flujo de trabajo (o seleccionar uno existente) En tu proyecto o en el Página de Flujos de trabajo independientes .

---

×

close

Asegúrate de estar en el Sus flujos de trabajo sección.

Hacer clic Crear un flujo de trabajo.

Determinar el cronograma o el evento que desencadena tu tarea. ( Ver una comparación .)

Hacer clic Agregar tarea y seleccione Servicio Web .

---

×

close

Elija su método de autenticación. Sus opciones incluyen las siguientes:

---

×

close

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

Haga clic en Siguiente.

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.

---

×

close

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.

Hacer clic Siguiente.

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.

---

×

close

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.

Elige tu servicio web Pedido método. Ver Métodos de servicios web para obtener más información sobre cada método.

---

×

close

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.

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 .

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.

Si elige publicar, colocar o parchear, deberá elegir el formato de su cuerpo. Las opciones incluyen JSON , URL codificada , XML , y Texto sin formato.

---

×

close

Determina cómo quieres especificar el cuerpo de tu solicitud. Puedes agregar el cuerpo como Pares clave-valor o Texto libre .

Consejo Q: El número máximo de caracteres tanto para pares clave-valor como para texto libre es 75 000.

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.

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 .

  

  Consejo Q: Asegúrese de que los datos introducidos sean un JSON válido. Al usar texto dinámicoAsegúrese de que no se incluyan caracteres especiales.

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

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 .

Si seleccionó Texto libre, ingrese los parámetros del cuerpo en el formato seleccionado.

---

×

close

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.

Para probar su servicio web, haga clic en Ejecutar prueba .

---

×

close

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.

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.

Atención: Los datos de una tarea fallida no se pueden transferir a otra tarea. El texto dinámico se mostrará como un valor nulo.

Cuando termine de configurar su flujo de trabajo, haga clic en Ahorrar .

Consejo Q: Las tareas del servicio web tienen un tiempo de espera de 16 segundos. Si una llamada al servicio web tarda más de 10 segundos, el flujo de trabajo fallará.

Uso del Asistente de IA para la configuración de Tarea

Atención: Solo puede utilizar la asignación automática si un administrador de Marca/organización ha habilitado la función Asistencia de IA para configurar Flujos de trabajo permiso para su organización en el Administración pestaña.

El Asistente de IA puede configurar la integración de API en tareas de servicio web leyendo la documentación de API disponible públicamente y configurando la tarea automáticamente.

Crear un flujo de trabajo con una tarea de servicio web.

Elija su método de autenticación. Para obtener más información, consulte Configuración de una Tarea de servicio web.

Hacer clic Prueba el Asistente de IA.

---

×

close

Seleccione el servicio web.

Describe la intención o solicitud de la llamada API .

Hacer clic Generar borrador.

Consejo Q: Si el Asistente de IA no puede generar un borrador, edite la solicitud y vuelva a intentarlo.

Revise la configuración de la API .

---

×

close

Para probar su servicio web, haga clic en Ejecutar prueba .

---

×

close

Hacer clic Agregar ruta personalizada para agregar rutas JSON o XML . Para obtener más información, consulte Configuración de una Tarea de servicio web.

Haga clic en Guardar.

Consejo Q: Si bien contamos con medidas de seguridad y estamos continuamente perfeccionando nuestros productos, la inteligencia artificial a veces puede generar resultados inexactos, incompletos o desactualizados. Antes de utilizar cualquier resultado de las funciones de IA de Qualtrics, debe revisar el resultado para comprobar su precisión y asegurarse de que sea adecuado para su caso de uso. Los resultados de las funciones de IA de Qualtrics no sustituyen la revisión humana ni la orientación profesional.

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.

Consejo Q: Todos los tipos de conexión son compatibles con mTLS. Para obtener más información, consulte la TLS mutuo sección.

Básico

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

---

×

close

Clave de API

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

---

×

close

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.

Consejo Q: Al crear una conexión OAuth, la URL de redireccionamiento será https://{dataCenter} qualtrics/oauth-client-service/redirect , donde {dataCenter} representa el valor asociado a su cuenta. Ver Esta página para obtener más detalles sobre cómo encontrar el centro de datos de su cuenta.

Para autenticarse usando OAuth 2.0:

---

×

close

Consejo Q: Para los usuarios que configuran credenciales de Google OAuth, incluya el siguiente parámetro al final de su punto final de token: ”?prompt=consent.”Si tiene parámetros de consulta existentes, el signo de interrogación no es necesario.

Consejo Q : Si tiene problemas para conectarse con Snowflake, asegúrese de que Los rangos de IP de Qualtrics están en la lista de permitidos .

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 .

---

×

close

Consejo Q: Solo puedes cambiar el nombre o eliminar las credenciales que hayas agregado tú mismo.

Advertencia: ¡Tenga cuidado al eliminar credenciales! Cualquier flujos de trabajo que utilice las credenciales dejará de funcionar cuando se eliminen las credenciales.

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.

Configuración su tarea de servicio web, seleccione sus credenciales y elija su solicitud.

---

×

close

En la sección Encabezados, ingrese X- API-TOKEN como la clave.

Para el valor, haga clic en el ícono de texto dinámico , {a} .

Seleccione sus credenciales de la lista.

---

×

close

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

Crea tu tarea de servicio web .

---

×

close

Elegir Autenticado .

---

×

close

Haga clic en Siguiente.

Añadir una cuenta de usuario.

---

×

close

Consejo Q: A Administrador de Marca/organización puede conectarse a una cuenta usando el Extensiones página.

---

×

close

Seleccione una tipo de conexión y complete sus credenciales.

---

×

close

Seleccionar Habilitar mTLS .

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”.

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”.

Cuando haya terminado, haga clic en Conectar Cuenta .

Continúe con la configuración de su servicio web .

Consejo Q: La validez de sus claves mTLS no se puede probar hasta que ejecute una llamada API a través de su servicio web, por lo que no verá un mensaje de error en esta página si ingresó sus claves incorrectamente. Intentar pruebas el servicio web antes de poner en marcha su flujo de trabajo .

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 comocurl https://api.example.com/parameters . Para los comandos curl que no son tan simples como este, proporcionaremos algunos parámetros comunes.

Consejo Q: Si está editando una tarea de servicio web existente, cualquier comando curl que importe sobrescribirá las configuraciones anteriores.

Consejo Q: Si está interesado en aprender más sobre curl de lo que cubrimos a continuación, le recomendamos leer un recurso externo al Soporte técnico de Qualtrics, como Documentación de IBM .

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:

• --cookie para enviar cookies con la solicitud.
• --Lo--location para seguir redirecciones.
• --max-time para establecer el tiempo máximo de solicitud.
• --oo--output para guardar la respuesta en un archivo.
• --insecure para permitir conexiones inseguras.
• --Ao--user-agent para especificar el agente de usuario.

Consejo Q: Si intenta importar un comando curl con parámetros no admitidos, aparecerá un mensaje de error que enumerará los parámetros no admitidos que utilizó. Se le dará la opción de continuar importando su comando curl con los parámetros no compatibles eliminados.

Importación de comandos Curl

Durante la configuración de la tarea del servicio web, haga clic en Importar cURL .

---

×

close

Pegue su comando curl en el cuadro.

---

×

close

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

Haga clic en Importar.

Los campos del servicio web se completarán automáticamente.

Consejo Q: Le recomendamos que vuelva a verificar sus campos antes de activar su flujo de trabajo.