脚本编写模式

此页面收集可在 Shell、PowerShell 和 CI 管道中轻松编写uip脚本的模式。此处没有任何内容特定于单个工具；每个模式都基于合同构建，即退出代码和JSON 信封在命令之间公开一致。

有用的默认值

三个设计决策使脚本编写变得简单：

1. JSON 是默认输出。无论您是在终端还是管道中，都不需要--output json 。
2. 标准输出仅为 JSON；否则均为标准错误。日志、进度条和人类可读的错误文本都将转到标准错误 (stderr) 中，因此捕获标准输出将为您提供干净的数据。
3. 退出代码范围较小，且稳定。五个值（ 0 、 1 、 2 、 3 、 4 ）涵盖所有记录的故障模式， 130表示用户取消。脚本无需解析字符串即可进行分支。

严格的 shell 选项

对于 bash/zsh，请使用以下内容开始脚本：

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

• -e — 收到任何非零退出命令时中止。
• -u — 因未定义变量而中止。
• -o pipefail — 从管道的任何阶段传播故障，而不仅仅是最后一个阶段。

对于 PowerShell：

$ErrorActionPreference = 'Stop'

根据退出代码创建分支

信封上的Result值一对一映射到流程退出代码。对退出代码进行分支，以便快速决策；打开信封了解详细信息（请参阅退出代码以获取完整表格）。

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

超出信封范围读取值

使用--output-filter (JMESPath) 在源中提取值，而不是通过jq进行管道传输：

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

--output plain为标量筛选器结果返回纯值（不带引号）。对于数组和对象， --output json保留以下结构：

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

如果您更喜欢jq端到端，请捕获原始 JSON 和链：

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

这两种方法产生的值相同。--output-filter速度更快，并且在 CLI 解析时即可进行验证； jq为您提供完整的 JMESPath以及jq 特定的结构，例如[-1] （最后一个元素）和to_entries 。

出现身份验证错误时重新进行身份验证（退出次数 2）

访问令牌过期。在长时间运行的脚本中，模式为：运行命令，如果令牌已消失，则回退到uip login ，重试一次，然后硬性失败。

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

有限制重试次数——单次身份验证重试即可处理令牌过期；进一步的重试将掩盖配置错误的凭据和消耗率限制。

轮询长时间运行的操作

某些操作将在 Orchestrator 端异步完成：

• 作业执行 — 使用uip or jobs start --wait-for-completion为您让 CLI 轮询。默认超时为 300 秒，可通过--timeout进行调整。轮询间隔为 5 秒，并可通过--poll-interval进行调整。
• 解决方案部署 — uip solution deploy run进行内部轮询，默认超时为 360 秒。
• 测试执行 — uip tm testsets run启动运行，返回ExecutionId ，并立即退出0 。要在运行完成之前阻止，请链接uip tm wait （轮询并在超时时退出2 ）。要在等待后读取通过/失败判断，请检查Data.Failed中的uip tm report get 。请参阅uip tm 测试集、 uip tm 执行和uip tm 等待。

当内置轮询过于粗略时，或当最终状态需要自定义处理时，请自行轮询：

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

始终按时间限制循环 — 否则，最终处于“待处理”循环的“发生故障”的作业将永远阻止：

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

幂等管道

许多uip命令在设计上均具有幂等性 — 使用相同的参数重新运行这些命令，要么返回现有资源，要么不执行任何操作：

• uip solution publish — 重新发布具有相同名称和版本的包将返回现有版本。
• uip tools install — 如果已安装工具，则为无操作。
• uip or processes create — 将在文件夹中重复名称的情况下失败；在这种情况下，请使用uip or processes update-version或uip or processes edit 。
• uip resource assets deploy --from-file — 按键更新或插入。

将这些功能与set -e结合使用，即可构建在部分故障后可以安全重新运行的管道，无需执行清理步骤。

将数据与日志分离

标准输出为 JSON。标准错误 (Stderr) 至关重要。独立重定向：

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

这在 CI 中尤其重要：与数据流内联打印进度指示器或npm输出的作业将生成损坏的 JSON，以供后续步骤使用。

处理空结果

如果命令在Data中失败且行数为零，则退出0 — 列表查询有效，但没有任何匹配项。使用--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

不对表格输出中缺少Name进行模式匹配；此格式无法解析。

在 CI 中固定版本

可重现的管道需要固定 CLI 和（可选）工具。由于工具版本默认跟踪 CLI 的 MAJOR.MINOR 行，因此仅固定 CLI 通常就足够了：

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

为了在不同补丁级别之间严格重现，还要固定工具：

uip tools install @uipath/orchestrator-tool@1.0.2

有关详细信息，请参阅工具（插件）— 版本解决方案。

禁止显示交互式提示

当标准输出为 TTY 时，默认情况下有少数uip命令处于交互式状态：

• uip login — 如果未传递--tenant ，则提示选择租户。
• uip skills install/update/uninstall — 如果未传递--agent ，则提示输入目标智能体。
• uip completion — 提示您确认安装路径。
• uip tools search — 如果未通过，则提示您输入查询。

在 CI 中，这些提示词可能会挂起作业。通过以下方式避免它们：始终传递相关标志（ --tenant 、 --agent 、 --print / completion上的显式 shell ），或确保标准输出不是 TTY（大多数 CI 运行程序已经处理此问题）。

在 CI 中禁用遥测

默认情况下，匿名遥测数据将发送到 UiPath 的 Application Insights。对于离线环境或严格环境：

export UIPATH_TELEMETRY_DISABLED=1

……或通过UIPATH_AI_CONNECTION_STRING指向您自己的实例。请参阅安装 UiPath CLI — 遥测。

另请参阅

• 退出代码— 权威表格。
• 输出格式— 信封和四种格式。
• 全局选项— --output 、 --output-filter 、 --log-level 、 --log-file 。
• 身份验证— 上述重试模式中引用的三个身份验证流程。
• CI/CD 方案— 完整的特定于平台的管道。