スクリプト パターン

このページでは、シェル、PowerShell、CI パイプラインで uip スクリプト化を容易にするパターンを収集します。ここでは、1 つのツールに固有のものはありません。すべてのパターンは、 終了コード と JSONエンベロープ がコマンド間で一貫して公開するコントラクトに基づいて構築されています。

便利なデフォルト

3 つの設計上の決定により、スクリプト作成が簡単になります。

1. JSON が既定の出力です。ターミナルでもパイプラインでも、 --output json は必要ありません。
2. Stdout は JSON のみです。それ以外はすべて stderr です。ログ、進行状況バー、人間が判読できるエラー テキストは stderr に移動するため、stdout をキャプチャするとクリーンなデータが得られます。
3. 終了コードは狭く安定しています。5 つの値 (0、 1、 2、 3、 4) で、文書化されたすべてのエラー モードと、ユーザーのキャンセルの 130 がカバーされます。スクリプトは、文字列を解析せずに分岐できます。

厳密なシェルオプション

bash / zsh の場合は、スクリプトを次のように開始します。

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

• -e — ゼロ以外から出たコマンドを中止します。
• -u — 未定義の変数で中止します。
• -o pipefail — 最後のステージだけでなく、パイプラインの任意のステージから失敗を伝播します。

PowerShell の場合:

$ErrorActionPreference = 'Stop'

終了コードでの分岐

エンベロープの Result 値は、プロセスの終了コードに 1 対 1 でマッピングされます。迅速な決定のために終了コードを分岐します。詳細については、封筒を開いてください(表全体については 、終了コード を参照してください)。

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 に加えて 、 [-1] (最後の要素)や to_entriesなどのjq固有の構造を提供します。

AuthenticationError での再認証 (exit 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

リトライを制限 — 1回の認証リトライがトークンの有効期限を処理します。それ以降にリトライを行うと、設定ミスのある資格情報がマスクされ、レート制限が書き込まれます。

長期実行操作のポーリング

一部の操作は 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 終了します)。待機後に合格/不合格の判定を確認するには、uip tm report getでData.Failedを調べます。「uip tm testsets」、「uip tm executions」、および「uip tm wait」をご覧ください。

組み込みのポーリングが粗すぎる場合、または終了状態がカスタム処理を必要とする場合は、自分自身をポーリングします。

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 と組み合わせることで、部分的な障害が発生した後にクリーンアップ手順なしで安全に再実行できるパイプラインを構築します。

ログからデータを分離する

Stdout は JSON です。Stderrは他のすべてです。これらを個別にリダイレクトします。

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

これはCIで特に重要です:データストリームと一緒に進捗インジケーター npm 出力をインラインで出力するジョブは、後のステップで使用するための壊れたJSONを生成します。

空の結果を処理する

Data の 0 行で成功したコマンドは、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のメジャーを追跡するためです。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

詳しくは ツール (プラグイン) — バージョン解決 を参照してください。

対話型プロンプトを抑制する

いくつかの uip コマンドは、stdout が TTY の場合、デフォルトで対話的です。

• uip login — テナントの選択を求め --tenant 渡さない場合に表示します。
• uip skills install/update/uninstall — --agent が渡されない場合に、ターゲット エージェントの入力を求めます。
• uip completion — インストール パスを確認するためのプロンプトを表示します。
• uip tools search — 何も渡されない場合にクエリの入力を求めます。

CI では、これらのプロンプトでジョブをハングさせることができます。関連するフラグ (--tenant、 --agent、 --print/explicit シェル on a completion) を常に渡すか、stdout が TTY ではないことを確認することで、これらを回避します (ほとんどの CI ランナーはすでにこれを処理しています)。

CI でのテレメトリの無効化

匿名のテレメトリは、既定で UiPath の Application Insights に送信されます。エアギャップ環境または厳密な環境の場合:

export UIPATH_TELEMETRY_DISABLED=1

…または、 UIPATH_AI_CONNECTION_STRINGを使用して独自のインスタンスを指定します。「 UiPath CLI をインストールする — テレメトリ」をご覧ください。

参照

• 終了コード — 権限のあるテーブル。
• 出力フォーマット — エンベロープと 4 つのフォーマット。
• グローバルオプション — --output、 --output-filter、 --log-level、 --log-file。
• 認証 — 上記のリトライ パターンで参照される 3 つの認証フローです。
• CI/CD レシピ — プラットフォーム固有の完全なパイプライン。