Padrões de script

Padrões de script do Shell, PowerShell e CI para o UiPath CLI, criados nos contratos de código de saída e envelope JSON.

Esta página coleta os padrões que facilitam o script de uip — no shell, PowerShell e pipelines de CI. Nada aqui é específico a uma única ferramenta; cada padrão baseia-se no contrato que o código de saída e o envelope JSON expõem de forma consistente entre comandos.

Padrões úteis

Três decisões de design tornam o script simples:

1. JSON é a saída padrão. Nenhum --output json é necessário, esteja você em um terminal ou um pipeline.
2. stdout é somente JSON; todo o resto é stderr. Os logs, as barras de progresso e o texto de erro legível por humanos vão para o stderr, portanto, a captura do stdout fornece dados limpos.
3. Os códigos de saída são estreitos e estáveis. Cinco valores (0, 1, 2, 3, 4) cobrem cada modo de falha documentado, mais 130 para cancelamento do usuário. Os scripts podem se ramificar sem analisar strings.

Opções de shell estritas

Para bash / zsh, inicie scripts com:

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

• -e anular em qualquer comando que saia diferente de zero.
• -u anular em uma variável indefinida.
• -o pipefail propagar uma falha de qualquer estágio de um pipeline, não apenas do último.

Para o PowerShell:

$ErrorActionPreference = 'Stop'

Ramificação em códigos de saída

O valor Result no envelope mapeia um a um para o código de saída do processo. Ramifique o código de saída para decisões rápidas; abra o envelope para obter detalhes (consulte Códigos de saída para ver a tabela 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

Lendo valores fora do envelope

Use --output-filter (JmesPath) para extrair valores na origem, em vez de canalizar através de jq:

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

--output plain o valor simples (sem aspas) de um resultado de filtro escalar. Para arrays e objetos, --output json mantém a estrutura:

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

Se você preferir jq de ponta a ponta, capture JSON bruto e encadee:

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

Ambas as abordagens produzem o mesmo valor. é --output-filter rápido e valida no tempo de análise de CLI; jq oferece o JmesPath completo e construções específicas do jq, como [-1] (último elemento) e to_entries.

Reautenticação em AuthenticationError (saída 2)

Os tokens de acesso expiram. Em um script de execução longa, o padrão é: execute o comando, volte para uip login se o token estiver perdido, tente novamente uma vez, então falhe.

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

Manter repetições limitadas — uma única tentativa de autenticação lida com a expiração do token; outras tentativas mascarariam uma credencial incorreta e gravariam limites de taxa.

Ramificação em ErrorCode e Retry

Cada envelope de falha também carrega ErrorCode (uma taxonomia estável como rate_limited, network_error, not_found) e Retry (RetryWillNotFix, RetryLater, RetryAfter1Second, …) — consulte Formatos de saída — o envelope. Eles são preenchidos automaticamente, mesmo quando um comando não os define explicitamente, e são mais refinados do que o código de saída individualmente: a saída 1 isoladamente não informa se uma falha de not_found e de rate_limited ambos mapeadas para ela valem a pena tentar novamente.

if ! uip or folders list --output json > folders.json; then
  RETRY=$(jq -r '.Retry // empty' folders.json 2>/dev/null)
  case "$RETRY" in
    RetryLater|RetryAfter*) sleep 5; uip or folders list --output json > folders.json ;;
    RetryWillNotFix|"") exit 1 ;;
  esac
fi

Prefira a ramificação em Retry a analisar ErrorCode string por string quando tudo de que você precisa é "devo tentar novamente" — é o campo projetado exatamente para essa decisão.

Pesquisa de operações de longa duração

Algumas operações são concluídas de forma assíncrona no lado do Orchestrator:

• Execução de trabalho — use uip or jobs start --wait-for-completion para ter a pesquisa da CLI para você. O tempo limite padrão é de 300 segundos, configurável com --timeout. O intervalo de pesquisa é de 5 segundos, configurável com --poll-interval.
• Implantação da solução — uip solution deploy run pesquisa internamente com um tempo limite padrão de 360 segundos.
• Execução de testes — uip tm testsets run inicia a execução, retorna um ExecutionId e sai imediatamente com 0. Para bloquear até que a execução seja concluída, encadee uip tm wait (que pesquisa e sai de 2 no tempo limite). Para ler o veredicto de aprovação/falha após aguardar, inspecione Data.Failed em uip tm report get. Consulte uip tm testessets, uip tm execuções e uip tm Wait.

Quando a pesquisa integrada for muito bruta ou quando o estado terminal precisar de tratamento personalizado, pesquise você mesmo:

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" --output-filter "Data.State" --output plain)
  case "$STATE" in
    Successful) echo "done"; break ;;
    Faulted|Stopped) echo "job $STATE"; exit 1 ;;
    *) sleep 10 ;;
  esac
done

Sempre limite o loop no tempo — um trabalho com falha que termina em um loop Pendente será bloqueado para sempre:

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

Pipelines idempotentes

Muitos comandos uip são idempotentes por design — reexecutá-los com os mesmos argumentos retorna o recurso existente ou não faz nada:

• uip solution publish a republicação de um pacote com o mesmo nome e versão retorna a versão existente.
• uip tools install um não operacional se a ferramenta já estiver instalada.
• uip or processes create — falhará no nome-na-pasta duplicado; use uip or processes update-version ou uip or processes edit nesse caso.

uip or assets create é idempotente — ele falha em um nome na pasta duplicado e não há sinalizador upsert único. Para um loop de implantação reexecutável, liste primeiro e ramificar para create ou update por linha — consulte Como fazer: gerenciar recursos do Orchestrator — implantar ativos em massa.

Combine esses com set -e para criar pipelines seguros para serem executados novamente após uma falha parcial sem etapas de limpeza.

Separando dados de logs

stdout é JSON. stderr é todo o resto. Redirecione-os de forma independente:

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

Isso é especialmente importante no CI: um trabalho que imprime indicadores de progresso ou saída npm em linha com o fluxo de dados produzirá JSON fragmentado para etapas posteriores o consumirem.

Tratamento de resultados vazios

Um comando que é bem-sucedido com zero linhas em Data sai de 0 — a consulta da lista funcionava, mas não havia correspondência. Detectar isso com --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

Não faça a correspondência padrão na ausência de um Name na saída da tabela; não é um formato analisável.

Fixação de versões no CI

Os pipelines reprodutíveis exigem a conexão da CLI e (opcionalmente) das ferramentas. Como as versões da ferramenta rastreiam a linha MAJOR.MINOR da CLI por padrão, fixar a CLI isoladamente geralmente é suficiente:

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

Para reprodutibilidade rigorosa entre níveis de patch, fixe também ferramentas:

uip tools install @uipath/orchestrator-tool@1.0.2

Consulte Ferramentas ( plugins ) — resolução de versão para os detalhes.

Supressão de prompts interativos

Alguns comandos uip são interativos por padrão quando stdout é um TTY:

• uip login — solicita a seleção do tenant se --tenant não for passado.
• uip skills install/update/uninstall solicita o agente de destino se --agent não for aprovado.
• uip completion solicita a confirmação do caminho de instalação.
• uip tools search solicita uma consulta se nenhuma for aprovada.

No CI, esses prompts podem travar um trabalho. Evite-os sempre passando os sinalizadores relevantes (--tenant, --agent, shell --print/explicit em completion) ou garantindo que o stdout não seja um TTY (a maioria dos executores de CI já cuidam disso).

Desabilitando a telemetria no CI

A telemetria anônima é enviada para o Application Insights da UiPath por padrão. Para ambientes isolados ou estritos:

export UIPATH_TELEMETRY_DISABLED=1

...ou aponte-o para sua própria instância por meio de UIPATH_AI_CONNECTION_STRING. Consulte Instalação do UiPath CLI — Telemetria.

Veja também

• Códigos de saída — a tabela autorizada.
• Formatos de saída — o envelope e os cinco formatos.
• Opções globais — --output, --output-filter, --log-level, --log-file.
• Autenticação — os fluxos de autenticação referenciados no padrão de nova tentativa acima.
• Receitas de CI/CD — pipelines completos específicos da plataforma.