Saltar al contenido principal
Loading...
Skip to article
  • Qualtrics Platform
    Qualtrics Platform
  • Customer Journey Optimizer
    Customer Journey Optimizer
  • XM Discover
    XM Discover
  • Qualtrics Social Connect
    Qualtrics Social Connect

Tarea de servicio web


Was this helpful?


This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

The feedback you submit here is used only to help improve this page.

That’s great! Thank you for your feedback!

Thank you for your feedback!


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:

Consejo Q: Esta página contiene referencias a la API de Qualtrics, que es una función que requiere permiso especial para acceder a. Si está interesado en obtener acceso a esta función, póngase en contacto con su Administrador de organización para obtener más información.
Atención: La configuración de un servicio web a menudo requiere conocimientos de programación avanzados. Aunque nuestro equipo de soporte está encantado de ayudar con los aspectos básicos de poner información en el servicio web, no podemos proporcionar soporte en los aspectos de programación.
Atención: las tareas de servicio web solo admiten los siguientes tipos de contenido: codificado en URL, XML, JSON y texto sin formato.
Qtip: Are you setting up your web service from an API doc? Your setup can be much faster if you import a curl command.

Configuración de una tarea de servicio web

Attention: The output from the call being made in your Web Service task has a limit of 1MB.

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.
    En la pestaña Flujos de trabajo, hacer clic en crear un flujo de trabajo y luego iniciar cuando se recibe un evento
  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.
    el evento de servicio web
  6. Seleccione su método de autenticación. Sus opciones incluyen:
    seleccionar el tipo de autenticación y hacer clic en Siguiente

    • 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.
    añadir una cuenta de usuario o seleccionar una existente

    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.
    button that says get a head star by importing curl commands; task summary field
  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.
    seleccionar la solicitud e introducir una URL

    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.
    añadir parámetros de cuerpo al servicio Web y, a continuación, añadir un par clave-valor a la solicitud de cuerpo

    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.
    El cuerpo está configurado en texto libre, por lo que en lugar de pares de valores clave, hay un gran campo de texto

    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.
    Ejecutar botón de prueba. sección con el nombre de texto dinámico donde se añaden las rutas JSON

    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.
Consejo Q: Las tareas de servicio web tienen un tiempo de espera de 16 segundos. Si una llamada al servicio web dura más de 10 segundos, el flujo de trabajo fallará.

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.

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

Básico

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

agregando una nueva cuenta de autenticación básica

  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.

añadiendo una nueva cuenta de API

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

Para autenticarse con OAuth 2.0:

añadir una nueva cuenta OAuth

  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.
Consejo Q: Para los usuarios que configuren las credenciales de Google OAuth, incluya el siguiente parámetro al final de su punto de acceso de token: “?petición=consentimiento”. 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 elementos autorizados.

&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.
el botón renombrar y eliminar junto a una cuenta

Consejo Q: Solo puede renombrar o eliminar las credenciales que haya añadido usted mismo.
Advertencia: Tenga cuidado al borrar las credenciales. Cualquier workflow que utilice las credenciales dejará de funcionar cuando se borren las credenciales.

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.
    añadir un token de API como cabecera
  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.
    seleccionando el campo de token de API para la cabecera de token

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.
    Seleccionar una tarea de servicio web
  2. Seleccione Autenticado.
    La siguiente ventana muestra dos opciones: servicio web autenticado y no autenticado
  3. Haga clic en Siguiente.
  4. Añada una cuenta de usuario.
    Botón para añadir cuentas de usuario en la parte superior izquierda de la siguiente página de la ventana

    Consejo Q: Un administrador de organización puede conectarse a una cuenta mediante la página Extensiones.
    Mostrando extensión de servicio web en la pestaña de extensiones de la página de administración
  5. Seleccione un tipo de conexión y rellene sus credenciales.
    credenciales de servicio web
  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.
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 ha introducido sus claves de forma incorrecta. Pruebe el servicio web antes de que el flujo de trabajo entre en productivo.

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:

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.

Qtip: If you’re editing an existing web service task, any curl commands you import will overwrite previous configurations.
Qtip: If you’re interested in learning more about curl than what we cover below, we recommend reading a resource outside Qualtrics Support, such as IBM’s documentation.

Supported Curl Command Parameters

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

Parámetro Descripción Curl command Ejemplo
URL The endpoint or resource the web service should interact with. Full URL. https://datacenter.qualtrics.com/API/v3/directories/
HTTP Method Options like GET, POST, PUT, and so on. --X <command> or --request <command> Example 1: --X GET
Example 2: --request PUT
Encabezados Custom headers. --H or --header Example 1: --header 'Accept: application/json'
Example 2: --header 'Content-Type: application/json'
Cuerpo The body (or payload) for POST requests. --d or --data  --data '{

“description”: “Lists all open bugs”,

“jql”: “type = Bug and resolution is empty”,

“name”: “All Open Bugs”

}’

JSON format Replace having to specify JSON formatting in the header and data. --json This curl command replaces the following 3 tags:

 

--data [arg]

--header "Content-Type: application/json"

--header "Accept: application/json"

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:

Nombre Descripción Ejemplo
Aceptar Specify the media formats for the response. Accept: application/json
Content-type In a request, content type specifies the media type of the resource sent to the server. In the response, the content type indicates the media type of the resource enclosed in the message body. Content-Type: application/json
Autorización Provide credentials for accessing a protected resource. Authorization: Bearer token
ETag Provide a unique identifier for a specific version of a resource. ETag: "123456"
Content-length Set the size of the entity-body in the message. Content-Length: 1024
Origen Indicate the origin of the request. This can help with Cross-Origin Resource Sharing (CORS). Origin: https://example.com

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.
Qtip: If you try to import a curl command with unsupported parameters, an error message will appear listing the unsupported parameters you used. You’ll be given the option to continue importing your curl command with the unsupported parameters removed.

Importing Curl Commands

  1. During your web service task setup, click Import cURL.
    button that says get a head start by importing curl commands
  2. Paste your curl command in the box.
    Pasting a curl command in the doc

    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.
Qtip: We recommend double-checking your fields before you activate your workflow.

Preguntas frecuentes

Muchas de las páginas de este sitio han sido traducidas del inglés original utilizando la traducción automática. Aunque en Qualtrics hemos realizado nuestra diligencia debida para obtener las mejores traducciones automáticas posibles, la traducción automática nunca es perfecta. El texto original en inglés se considera la versión oficial, y cualquier discrepancia entre el inglés original y las traducciones automáticas no son legalmente vinculantes.