REST Web Services package

Utilice las actions en el REST Web Services package como métodos (ELIMINAR, OBTENER, EMPARCHAR, PUBLICAR, PONER) para enviar solicitudes y recibir respuestas de una API.

Configuración

Las siguientes configuraciones están disponibles para las actions de REST Web Services. Configure los ajustes adecuados para enviar una solicitud REST y recibir una respuesta. Cada método requiere parámetros específicos.

Nota: Cuando crea automatizaciones en la plataforma macOS y utiliza actions como (ELIMINAR, OBTENER, EMPARCHAR, PUBLICAR, PONER), los siguientes modos de autenticación no son compatibles:
  • Autenticación NTLM (usuario de AD)
  • Usuario de AD con sesión abierta
URI
Introduzca el URI del recurso API. Seleccione una de las siguientes opciones y ajuste la configuración en consecuencia:
  • Introducir el URI: Ingrese el URI directamente o seleccione el URI guardado como una variable de string.
  • Seleccionar credencial como URI: Utilice esta opción para seleccionar un URI que está guardado como una credencial en la Credential Vault. Utilice Credencial > Elegir para seleccionar la credencial directamente. También puede utilizar la opción Variable para seleccionar una credencial que esté asignada a una variable de credencial. Esta opción le permite ocultar los URI que contienen información confidencial, como códigos de autorización o claves de API.
Configuración del proxy
Establezca la configuración del proxy para las acciones del REST Web Services. Seleccione una de las siguientes opciones y ajuste la configuración en consecuencia:
  • Sistema: Seleccione esta opción para permitir que el Bot Agent use el proxy del sistema. El proxy del sistema es el proxy que configura en la máquina de ejecución del bot donde se ejecuta la automatización.
  • Personalizado: Seleccione esta opción para ajustar la configuración del proxy personalizada para la automatización. Configure los siguientes ajustes:
    • Host: El nombre del host o la dirección IP del servidor proxy.
    • Puerto: El número de puerto del servidor proxy.
    • Nombre de usuario (opcional): El nombre de usuario para autenticar el servidor proxy.
    • Contraseña (opcional): La contraseña para autenticar el servidor proxy.
    Nota: Debe configurar el Nombre de usuario y la Contraseña para cualquier servidor proxy autenticado.
    Puede usar una de las opciones Credencial, Variable o String insegura para ajustar la configuración del proxy.
    • Credencial: Para seleccionar un valor disponible en la Credential Vault.
    • Variable: Para seleccionar la variable de credencial que está asignada a un valor.
    • String insegura: Para ingresar el valor manualmente o seleccionar un valor que esté asignado a una variable de string predefinida.
Modo de autenticación
Ajuste la configuración de autenticación para las acciones del REST Web Services. Seleccione una de las siguientes opciones y ajuste la configuración en consecuencia:
  • Sin autenticación: Seleccione esta opción a fin de acceder a los puntos finales que no requieren autenticación para acceder a sus servidores.
  • Token de usuario de la Control Room: Seleccione esta opción para usar el token generado cuando inicie sesión en la Control Room.
  • Básico: Seleccione esta opción para ingresar el Nombre de usuario y la Contraseña para autenticar las llamadas a la API del REST Web Services. Esta opción agrega un encabezado llamado Autorización que contiene una representación en string codificada en base64 del Nombre de usuario y la Contraseña a la llamada de la API.
  • Usuario de AD con sesión abierta: Seleccione esta opción para elegir la autenticación basada en Active Directory (AD). Los usuarios de AD que están autorizados para acceder a la API relacionada se autentican a través de AD. No se necesitan credenciales en la solicitud.
  • Autenticación de Windows NT LAN Manager (NTLM) (Usuario AD): Seleccione esta opción para elegir una autenticación NTLM de desafío-respuesta. Configure los siguientes ajustes:
    • Dominio: Ingrese el dominio en el que se debe autenticar la llamada API. También puede seleccionar una variable de tipo string que esté asignada al dominio o al host.
    • Nombre de usuario (opcional): El nombre de usuario para autenticar la llamada a la API.
    • Contraseña (opcional): La contraseña para autenticar la llamada a la API.
    Puede usar una de las opciones Credencial, Variable o String insegura para configurar el nombre de usuario y la contraseña. Recomendamos que utilice la opción Credencial para elegir una credencial de la Credential Vault o utilice una variable de credencial.
  • Gestión de OAuth2 - Control Room: Seleccione esta opción para elegir una conexión administrada por la Control Room ‌OAuth como la opción de autenticación. Para obtener más información, consulte Configure ‌OAuth connections in Control Room.

    El siguiente video muestra cómo utilizar la conexión ‌OAuth en REST Web Services:

Encabezado
Agregue encabezados personalizados para incluir metadatos adicionales en las solicitudes de la API. No todos los métodos requieren un encabezado. Puede agregar encabezados, como Autorización, Aceptar juego de caracteres, Tipo de contenido, Control de la caché, Usuario-agente, etc.

Haga clic en Agregar encabezado y siga los indicadores en el modal Encabezado personalizado para agregar los encabezados requeridos. Puede seleccionar una credencial almacenada en la Credential Vault, o una variable de credencial, o ingresar el encabezado directamente como una string insegura.

Tipo de contenido
El encabezado Tipo de contenido define el tipo de medio del contenido en el cuerpo de la solicitud. Las actions de REST Web Services admiten los siguientes tipos de archivos:
  • application/x-www-form-urlencoded: Codifica los parámetros en un formato de string de consulta URL.
  • JSON (aplicación/json): Introduce un cuerpo de solicitud en formato JSON.
  • XML (aplicación/xml): Introduce un cuerpo de solicitud en formato XML.
  • Texto (texto/sin formato): Ingresa un cuerpo de solicitud de tipo texto en formato de texto sin formato.
  • XML (texto/xml): Ingresa un cuerpo de solicitud de tipo texto en formato XML.
  • HTML (texto/html): Ingresa un cuerpo de solicitud de tipo texto en formato HTML.
  • datos de formulario de varias partes: Permite incluir tanto texto como archivos en el cuerpo de la solicitud. Este tipo de contenido admite todos los formatos de archivo que la API admite. Puede utilizar este tipo de contenido para enviar varias partes en una sola solicitud, que por lo general incluye datos de texto (como campos de formulario) y potencialmente una carga de archivo. Este tipo de contenido también admite la transmisión de archivos.
    Puede leer un flujo de archivo después de asignarlo a una variable de tipo archivo. Por ejemplo, puede leer un flujo de archivo asignado a una variable en una ubicación de OneDrive. Para obtener más información, consulte action Asignar archivo.
    FileStream en el Servicio web de REST
  • Binario: Utilice Binary para enviar archivos sin procesar, como imágenes, vídeos y archivos de audio. Puede cargar los archivos usando una de las siguientes opciones:
    • Variable: Asigne una variable de archivo para cargar un archivo desde el escritorio o dentro de la Control Room. También puede usar esta opción para transmitir archivos desde una ubicación de almacenamiento.
    • Archivo de Control Room: Cargue un archivo disponible en el almacenamiento de la Control Room.
    • Archivo de escritorio: Cargue un archivo directamente desde el escritorio.
  • Personalizado
    Personalizado: Agregue contenido personalizado que no se incluya en el tipo de contenido estándar. Por ejemplo, cuando migra de la versión 11.x a Automation 360, el siguiente valor no se incluye en ninguno de los tipos de contenido estándar: application/vnd.whispir.message-v1+json.

Para application/x-www-form-urlencoded y multipart/form-data, haga clic en Agregar parámetro y siga los indicadores en el modelo Parámetro para agregar los parámetros de encabezado requeridos.

Para otros tipos de contenido, puede usar la opción Ingresar los parámetros o la opción Seleccionar credencial como parámetros para agregar los parámetros. La opción Seleccionar credencial como parámetros le permite agregar datos confidenciales como encabezados de solicitud.

Agregar sustitución
La opción Agregar sustitución permite introducir variables en el cuerpo de la solicitud REST. Esta opción está disponible para JSON (aplicación/json), XML (aplicación/xml), Texto (texto/simple), XML (texto/xml), HTML (texto/html) y Personalizado encabezados de tipo de contenido.
Una variable es una representación simbólica de datos y permite acceder a un valor sin tener que introducirlo manualmente cuando lo necesite. Por ejemplo, considere la siguiente solicitud de cuerpo REST:
{
   "name":"{{name}}",
   "email":"{{email}}",
   "status":"Active"
}
En el cuerpo de solicitud anterior, puede sustituir las variables incluidas entre corchetes dobles si hace clic en Agregar sustitución y añade los valores requeridos.
Opciones avanzadas
Capturar respuesta ante fallas: Seleccione la casilla de verificación para capturar la respuesta ante fallas, excepto para la respuesta Éxito/Aceptar. El sistema captura los detalles de la respuesta ante fallas en el cuerpo de la respuesta. Esta opción está disponible en las acciones de los métodos Eliminar, Obtener, Parche, Publicar y Colocar.
Permitir una conexión insegura cuando se utiliza https: Seleccione la casilla de verificación para permitir una conexión no segura cuando se utiliza el protocolo https. Esta opción está disponible en todas las acciones.
Aceptar Cookies: Seleccione la casilla de verificación para capturar automáticamente las cookies de sesión de las respuestas del servidor. Las siguientes funciones se activan en segundo plano cuando se selecciona esta casilla de verificación.
  • Capturar: El sistema captura las cookies de sesión que el servidor incluye en las respuestas.
  • Almacenamiento seguro: El sistema cifra las cookies capturadas dentro de la memoria del proceso, lo que garantiza que nunca se almacenen de forma permanente y que sean inaccesibles fuera de su sesión de automatización.
  • Reutilizar: El sistema incluye automáticamente las cookies en llamadas REST posteriores, lo que elimina la gestión manual de cookies y mejora la confiabilidad de la automatización.
  • Gestión de varias cookies: El sistema permite que la automatización gestione varias cookies que devuelve el servidor, lo que garantiza que se incluyan todas las credenciales de autenticación necesarias.
  • Destrucción: El sistema destruye automáticamente las cookies capturadas cuando finaliza la sesión de automatización o la ejecución del bot, lo que garantiza la seguridad y la privacidad de los datos.

Esta opción está disponible en las acciones de los métodos Eliminar, Obtener, Parche, Publicar y Colocar.

Nota: Las cookies capturadas son específicas del dominio desde el que se originan y no se utilizarán automáticamente para llamadas REST posteriores realizadas a diferentes dominios. Esto significa que las cookies capturadas de domainA.com no se utilizarán para solicitudes de domainB.com.
Descargar archivo: Seleccione esta casilla de verificación para descargar el archivo binario disponible en el URI a una ubicación específica. Asegúrese de ingresar la ruta del archivo deseada con el nombre y la extensión. Por ejemplo: <C:/Users/Downloads/image01.jpg>

Esta opción solo está disponible en la acción Obtener método. El sistema muestra un mensaje de error cuando ocurre uno de los siguientes escenarios:

  • URI no válido: Si el URI facilitado es incorrecto.
  • No se encontró el archivo: Si la respuesta de la API está vacía porque el archivo no existe en la ubicación especificada.
  • Permisos insuficientes: Si no tiene permisos de escritura para la ubicación de descarga.
  • Discrepancia de extensión de archivo: Si la extensión del archivo no coincide con el tipo esperado.

Active la casilla de verificación Sobrescribir archivo si ya existe para sobrescribir un archivo existente con una nueva versión.

Espere a que se complete la acción
Se puede establecer un valor de tiempo de espera cuando se envía una solicitud REST y se recibe una respuesta. Cuando realice actions como PUBLICAR, COLOCAR, ELIMINAR, PARCHAR y OBTENER, especifique el tiempo de espera (en milisegundos) en el campo Esperar a que la acción se complete. De manera predeterminada, el tiempo de espera es de 60 000 milisegundos
Configuración SSL/TLS
Utilice esta opción para cargar un archivo de certificado con o sin contraseña a fin de proporcionar autenticación adicional durante las llamadas a la API REST.

La configuración SSL/TLS utiliza el protocolo TLS mutuo (mTLS) para cifrar, autenticar y proteger las comunicaciones entre el URI de la API y el cliente. mTLS requiere que ambas entidades se autentiquen mutuamente mediante el intercambio de certificados. La transmisión de datos solo ocurre si ambas entidades autentican correctamente los certificados intercambiados.

El REST Web Services admite certificados de tipo .p12 para máquinas con Windows y formato .pfx para máquinas que no tienen Windows.

  • Ruta del archivo de almacén de claves (opcional): Cargue el archivo de certificado usando la opción Variable, Archivo de Control Room o Archivo del escritorio.
  • Contraseña del almacén de claves (opcional): Si el certificado está protegido por contraseña, puede autenticar la contraseña del certificado usando la opción Credential, Variable o String insegura. Para obtener más información sobre cómo almacenar contraseñas de forma segura en el almacén de Credenciales, consulte Credenciales y lockers en Credential Vault.
Asignar la salida a una variable
La salida de respuesta se captura en una variable de diccionario. Una variable de diccionario es un par de valores clave. Utilice el nombre del encabezado de la respuesta como clave para devolver el valor del encabezado o “Cuerpo” como la clave para devolver el cuerpo de la respuesta.

Esta opción está disponible en las acciones de los métodos Eliminar, Obtener, Parche, Publicar y Colocar.

Nota: La clave de respuesta con su valor está disponible en la variable de diccionario para mostrar el estado de respuesta de la API REST.
Para obtener una lista de los nombres de encabezado para el recurso API, realice estos pasos:
  1. Inserte una action de Loop después de la action de REST Web Services.
  2. Seleccione el iterador Para cada clave en el diccionario.
  3. En el campo Variable de diccionario, seleccione la variable que contiene la salida de la action de REST Web Services.
  4. Asigne el valor de cada clave a $prompt-assignment$.
  5. Insertar una action Registrar texto en archivo.
  6. Proporcione la ruta del archivo a un archivo de texto para contener la lista de nombres de encabezado.
  7. Inserte $prompt-assignment$ en el campo Introducir texto a registrar.
  8. Seleccione la opción Sobrescribir archivo existente.
  9. Haga clic en Guardar.

    Cuando usted ejecuta el bot, este imprime los nombres de encabezado del recurso API al archivo seleccionado.

Asignar archivo a una variable
Esta opción está disponible solo en la acción Obtener flujo de archivo. La acción Obtener flujo de archivo le permite asignar una variable de archivo al archivo disponible en el URI. Luego, puede usar esta variable de archivo en las acciones posteriores dentro de la sesión. Para obtener más información sobre cómo asignar una variable de archivo, consulte Uso de la acción Obtener flujo de archivos.

Pasar valores de manera segura

Usted puede pasar valores de forma segura desde la Credential Vault al servicio web especificando el locker, la credencial y el atributo en los siguientes campos de action compatibles:
  • URI
  • Encabezados personalizados
  • Cuerpo: Para el tipo de contenido application/x-www-form-urlencoded, haga clic en Agregar parámetro para seleccionar el valor desde la Credential Vault.

    Para todos los demás tipos de contenido, seleccione la opción Seleccionar una credencial como parámetros y haga clic en Elegir.

Actions en el package de REST Web Services

Action Descripción
Método DELETE Elimina el recurso que es identificado por la URI.
Método Get Recupera la información identificada por los parámetros incluidos en la URI. No hay Tipo de contenido para el método GET porque todos los parámetros se pasan como parte de la URI.

Las limitaciones y características del método GET incluyen lo siguiente:

  • La extensión de la URI se limita a 2 048 caracteres.
  • Todos los parámetros se pasan en la URI.
  • El método GET expone los datos que se encuentran en la URI, lo que hace que sea menos seguro que el método POST.
  • GET no cambia ningún dato, lo que hace que sea seguro para todos los usuarios, independientemente de la autorización.

Consulte Uso del método Get.
Método PATCH Modifica el recurso que es identificado por la URI.
Método Post Crea un nuevo recurso en la URI.
  • Los parámetros son pasados al cuerpo de la solicitud.
  • No hay límite de extensión para el cuerpo de una solicitud.

Consulte Uso del método Post.
Método PUT Actualiza o reemplaza un registro basado en los parámetros pasados en la URI o el cuerpo. Consulte Utilizar el método Put.

Proxy support

If your device is configured with a proxy, all outbound requests from this package are routed through the proxy server. See Conectar Bot Agent a un dispositivo con un proxy.