Patrones de scripting

Esta página recopila los patrones que hacen que uip sea fácil ejecutar scripts en shell, PowerShell y procesos de CI. Nada aquí es específico de una sola herramienta; cada patrón se basa en el contrato que el código de salida y el sobre JSON exponen de forma coherente en todos los comandos.

Valores predeterminados útiles

Tres decisiones de diseño hacen que la creación de scripts sea sencilla:

1. JSON es la salida predeterminada. No --output json necesario, tanto si estás en un terminal como en un proceso.
2. La salida estándar es solo JSON; todo lo demás es stderr. Los registros, las barras de progreso y el texto de error legible por humanos van a stderr, por lo que capturar stdout te proporciona datos limpios.
3. Los códigos de salida son estrechos y estables. Cinco valores (0, 1, 2, 3, 4) cubren cada modo de fallo documentado, más 130 para la cancelación del usuario. Los scripts pueden ramificarse sin analizar cadenas.

Opciones de shell estrictas

Para bash/zsh, inicia los scripts con:

#!/usr/bin/env bash
set -euo pipefail

• -e — abortar en cualquier comando que salga distinto de cero.
• -u — abortar en una variable no definida.
• -o pipefail — propaga un fallo desde cualquier etapa de un proceso, no solo la última.

Para PowerShell:

$ErrorActionPreference = 'Stop'

Ramificación en códigos de salida

El valor Result del sobre se asigna uno a uno al código de salida del proceso. Rama en el código de salida para decisiones rápidas; abre el sobre para ver los detalles (consulta Códigos de salida para ver la tabla completa).

if uip or folders list --output-filter "Data[?Name=='Shared'] | [0]" > shared.json; then
  echo "Shared folder found"
else
  case $? in
    2)  echo "re-authenticating"; uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET --tenant "$UIPATH_TENANT" ;;
    3)  echo "bad flag — aborting"; exit 3 ;;
    *)  echo "unexpected failure"; exit 1 ;;
  esac
fi

Leer valores fuera del sobre

Usa --output-filter (JMESPath) para extraer valores en el origen, en lugar de canalizarlos a través de jq:

FOLDER_KEY=$(uip or folders list --all --name Shared --output-filter "Data[0].Key" --output plain)

--output plain devuelve el valor simple (sin comillas) para un resultado de filtro escalar. Para matrices y objetos, --output json mantiene la estructura:

PROCESS_KEYS=$(uip or processes list --folder-path Shared --output-filter "Data[*].Key")
echo "$PROCESS_KEYS" | jq -r '.[]' | while read -r key; do
  uip or jobs start "$key"
done

Si prefieres jq de extremo a extremo, captura JSON sin procesar y encadena:

FOLDER_KEY=$(uip or folders list --all --name Shared | jq -r '.Data[0].Key')

Ambos enfoques producen el mismo valor. --output-filter es más rápido y se valida en el tiempo de análisis de CLI; jq te ofrece JMESPath completo más construcciones específicas de jq como [-1] (último elemento) y to_entries.

Volver a autenticarse en AuthenticationError (salida 2)

Los tokens de acceso caducan. En un script de larga duración, el patrón es: ejecuta el comando, recurre a uip login si el token no está, vuelve a intentarlo una vez y luego falla de forma contundente.

uip_retry() {
  uip "$@" && return 0
  local code=$?
  if [[ $code -eq 2 ]]; then
    uip login \
      --client-id env.UIPATH_CLIENT_ID \
      --client-secret env.UIPATH_CLIENT_SECRET \
      --tenant "$UIPATH_TENANT" >/dev/null
    uip "$@"
  else
    return $code
  fi
}

uip_retry or folders list --all

Mantén los reintentos limitados: un solo reintento de autenticación gestiona la caducidad del token; más reintentos enmascararían una credencial mal configurada y límites de tasa de quemado.

Sondeo de operaciones de larga duración

Algunas operaciones se completan de forma asíncrona en el lado de Orchestrator:

• Ejecución de trabajo: utiliza uip or jobs start --wait-for-completion para tener la encuesta CLI para ti. El tiempo de espera predeterminado es de 300 segundos, ajustable con --timeout. El intervalo de sondeo es de 5 segundos, ajustable con --poll-interval.
• Implementación de la solución: uip solution deploy run sondea internamente con un tiempo de espera predeterminado de 360 segundos.
• Ejecución de prueba: uip tm testsets run inicia la ejecución, devuelve un ExecutionId y sale inmediatamente con 0. Para bloquear hasta que se complete la ejecución, encadena uip tm wait (que sondea y sale de 2 en el tiempo de espera). Para leer el veredicto de aprobación/error después de esperar, inspecciona Data.Failed en uip tm report get. Consulta conjuntos de pruebas de uip tm, ejecuciones de uip tm y espera de uip tm.

Cuando el sondeo integrado sea demasiado basto, o cuando el estado del terminal necesite un manejo personalizado, sondeate a ti mismo:

JOB_KEY=$(uip or jobs start "$PROCESS_KEY" --output-filter "Data.Jobs[0].Key" --output plain)

while :; do
  STATE=$(uip or jobs get --job-key "$JOB_KEY" --output-filter "Data.State" --output plain)
  case "$STATE" in
    Successful) echo "done"; break ;;
    Faulted|Stopped) echo "job $STATE"; exit 1 ;;
    *) sleep 10 ;;
  esac
done

Siempre limita el bucle a tiempo: un trabajo defectuoso que termina en un bucle Pendiente de lo contrario se bloqueará para siempre:

DEADLINE=$(( SECONDS + 1800 ))
while (( SECONDS < DEADLINE )); do
  # … as above …
done
[[ $SECONDS -ge $DEADLINE ]] && { echo "timed out"; exit 1; }

Procesos idempotentes

Muchos comandos uip son idempotentes por diseño: volver a ejecutarlos con los mismos argumentos devuelve el recurso existente o no hace nada:

• uip solution publish — volver a publicar un paquete con el mismo nombre y versión devuelve la versión existente.
• uip tools install : no opera si la herramienta ya está instalada.
• uip or processes create — fallará si se duplica el nombre en la carpeta; utiliza uip or processes update-version o uip or processes edit en ese caso.
• uip resource assets deploy --from-file : upserts por clave.

Combínalos con set -e para crear procesos que sean seguros de volver a ejecutar después de un fallo parcial sin pasos de limpieza.

Separar datos de registros

La salida estándar es JSON. Stderr es todo lo demás. Redirígelos de forma independiente:

uip or folders list > folders.json 2> uip.log

Esto es especialmente importante en CI: un trabajo que imprime indicadores de progreso o una salida npm en línea con el flujo de datos producirá JSON alterado para que los pasos posteriores lo consuman.

Gestionar resultados vacíos

Un comando que tiene éxito con cero filas en Data sale 0 : la consulta de la lista funcionó, pero nada coincidió. Detectar esto con --output-filter:

COUNT=$(uip or folders list --all --name DoesNotExist --output-filter "length(Data)" --output plain)
if [[ "$COUNT" -eq 0 ]]; then
  echo "no match"
  exit 1
fi

No coincide con el patrón en ausencia de un Name en la salida de la tabla; no es un formato analizable.

Anclar versiones en CI

Los procesos reproducibles requieren fijar tanto la CLI como (opcionalmente) las herramientas. Dado que las versiones de la herramienta realizan un seguimiento de la línea MAYOR.MENOR de la CLI de forma predeterminada, suele bastar con fijar la CLI:

npm install -g @uipath/cli@1.0.0
uip tools install @uipath/orchestrator-tool   # resolves to latest 1.0.x

Para una reproducibilidad estricta en todos los niveles de parche, fija también las herramientas:

uip tools install @uipath/orchestrator-tool@1.0.2

Consulta Herramientas (complementos): resolución de versión para obtener más detalles.

Suprimir solicitudes interactivas

Un puñado de comandos uip son interactivos de forma predeterminada cuando la salida estándar es un TTY:

• uip login — solicita la selección de tenant si no se pasa --tenant .
• uip skills install/update/uninstall : solicita el agente de destino si no se pasa --agent .
• uip completion : solicita la confirmación de la ruta de instalación.
• uip tools search — solicita una consulta si no se pasa ninguna.

En CI, estas solicitudes pueden bloquear un trabajo. Evítalos pasando siempre los marcadores relevantes (--tenant, --agent, --print/shell explícito en completion) o asegurándote de que stdout no sea un TTY (la mayoría de los ejecutores de CI ya se encargan de esto).

Deshabilitar la telemetría en CI

La telemetría anónima se envía a Application Insights de UiPath de forma predeterminada. Para entornos aislados o estrictos:

export UIPATH_TELEMETRY_DISABLED=1

…o apúntalo a tu propia instancia a través de UIPATH_AI_CONNECTION_STRING. Consulta Instalar UiPath CLI: telemetría.

Ver también

• Códigos de salida : la tabla autorizada.
• Formatos de salida : el sobre y los cuatro formatos.
• Opciones globales : --output, --output-filter, --log-level, --log-file.
• Autenticación : los tres flujos de autenticación a los que se hace referencia en el patrón de reintento anterior.
• Recetas CI/CD : procesos completos específicos de la plataforma.