Skriptingmuster

Auf dieser Seite werden die Muster gesammelt, die das Skripting von uip einfach machen – in Shell, PowerShell und CI-Pipelines. Hier ist nichts spezifisch für ein einzelnes Tool; Jedes Muster baut auf dem Vertrag auf, den der Exitcode und der JSON-Umschlag konsistent über Befehle hinweg bereitstellen.

Nützliche Standardeinstellungen

Drei Designentscheidungen machen die Skripterstellung einfach:

1. JSON ist die Standardausgabe. Kein --output json erforderlich, unabhängig davon, ob Sie sich in einem Terminal oder einer Pipeline befinden.
2. „Stdout“ ist nur JSON; alles andere ist standardr. Protokolle, Fortschrittsleisten und visuell lesbarer Fehlertext werden in STedRr umgewandelt, sodass Sie durch die Erfassung von Standardfehlern saubere Daten erhalten.
3. Austrittscodes sind schmal und stabil. Fünf Werte (0, 1, 2, 3, 4) decken jeden dokumentierten Fehlermodus ab, plus 130 für den Benutzerabbruch. Skripte können verzweigt werden, ohne Zeichenfolgen zu analysieren.

Strikte Shell-Optionen

Beginnen Sie für bash/zsh die Skripts mit:

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

• -e – jeden Befehl abbrechen, der nicht bei Null beendet wird.
• -u – Abbruch für eine nicht definierte Variable.
• -o pipefail – einen Fehler aus einer beliebigen Phase einer Pipeline übertragen, nicht nur aus der letzten.

Für PowerShell:

$ErrorActionPreference = 'Stop'

Verzweigungen bei Exitcodes

Der Wert Result auf dem Umschlag wird dem Prozessbeendigungscode 1:1 zugeordnet. Verzweigen Sie den Exit-Code für schnelle Entscheidungen; Öffnen Sie den Umschlag für Details (die vollständige Tabelle finden Sie unter Exit-Codes ).

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

Lesen von Werten aus dem Umschlag

Verwenden Sie --output-filter (JMESPath), um Werte an der Quelle zu extrahieren, anstatt sie durch jq zu Rufen:

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

--output plain gibt den leeren Wert (ohne Anführungszeichen) für ein skalares Filterergebnis zurück. Für Arrays und Objekte behält --output json die Struktur bei:

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

Wenn Sie jq End-to-End bevorzugen, erfassen Sie unformatierte JSON und Kette:

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

Beide Ansätze erzeugen den gleichen Wert. --output-filter ist schneller und wird zur CLI-Parse-Zeit validiert; jq bietet Ihnen den vollständigen JMESPath sowie jq-spezifische Konstrukte wie [-1] (letztes Element) und to_entries.

Erneute Authentifizierung bei AuthenticationError (2 beenden)

Zugriffstoken laufen ab. In einem Skript mit langer Ausführungszeit lautet das Muster: Führen Sie den Befehl aus, greifen Sie auf uip login zurück, wenn das Token nicht mehr verfügbar ist, versuchen Sie es einmal erneut und schlagen Sie dann einen erneuten Fehler ein.

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

Halten Sie Wiederholungen begrenzt – eine einzelne Authentifizierungswiederholung verarbeitet den Tokenablauf; Weitere Wiederholungen würden falsch konfigurierte Anmeldeinformationen und Verbrauchsrate-Limits maskieren.

Abrufvorgänge mit langer Ausführungszeit

Einige Vorgänge werden asynchron auf der Seite des Orchestrator abgeschlossen:

• Auftragsausführung – Verwenden Sie uip or jobs start --wait-for-completion , um die CLI-Abfrage für Sie zu erhalten. Das Standard-Timeout beträgt 300 Sekunden und ist mit --timeout anpassbar. Das Abrufintervall beträgt 5 Sekunden, anpassbar mit --poll-interval.
• Lösungsbereitstellung – uip solution deploy run fragt intern mit einem Standard-Timeout von 360 Sekunden ab.
• Testausführung – uip tm testsets run startet die Ausführung, gibt ein ExecutionId zurück und wird sofort mit 0 beendet. Um zu blockieren, bis die Ausführung abgeschlossen ist, verketten Sie uip tm wait (die 2 beim Timeout abfragt und beendet). Um das Bestehen-/Nichtbestehen-Ergebnis nach dem Warten zu lesen, überprüfen Sie Data.Failed in uip tm report get. Siehe UIP-TM-Testsätze, UIP-TM-Ausführungen und UIP-TM-Wait.

Wenn die integrierten Abrufe zu oberflächlich sind oder wenn der Endstatus benutzerdefinierte behandelt werden muss, fragen Sie sich selbst:

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

Schließen Sie die Schleife immer rechtzeitig – ein fehlerhafter Auftrag, der in einer ausstehenden Schleife endet, wird andernfalls für immer blockiert:

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

Idempotente Pipelines

Viele uip -Befehle sind von Natur aus idempotent – wenn sie mit denselben Argumenten erneut ausgeführt werden, wird entweder die vorhandene Ressource zurückgegeben oder nichts ausgeführt:

• uip solution publish – Das erneute Veröffentlichen eines Pakets mit demselben Namen und derselben Version gibt die vorhandene Version zurück.
• uip tools install – ein No-Op, wenn das Tool bereits installiert ist.
• uip or processes create – schlägt bei doppeltem Namen im Ordner fehl; verwenden Sie in diesem Fall uip or processes update-version oder uip or processes edit .
• uip resource assets deploy --from-file – Upserts nach Schlüssel durchführen.

In Kombination mit set -e können Sie Pipelines erstellen, die nach einem Teilfehler ohne Bereinigungsschritte sicher erneut ausgeführt werden können.

Trennen von Daten und Protokollen

Standardmäßig ist JSON. Standardmäßig ist alles andere. Leiten Sie sie unabhängig um:

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

Dies ist besonders wichtig in CI: Ein Auftrag, der Fortschrittsindikatoren oder eine npm -Ausgabe inline mit dem Datenstream ausgibt, erzeugt ein verändertes JSON, das spätere Schritte verwenden können.

Umgang mit leeren Ergebnissen

Ein Befehl, der mit null Zeilen in Data erfolgreich ist, beendet 0 – die Listenabfrage funktionierte, aber es wurde keine Übereinstimmung gefunden. Erkennen Sie dies mit --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

Kein Musterabgleich bei Fehlen eines Name in der Tabellenausgabe durchführen; Es ist kein analysierbares Format.

Anheften von Versionen in CI

Reproduzierbare Pipelines erfordern das Anheften sowohl der CLI als auch (optional) der Tools. Da Toolversionen standardmäßig die Zeile MaJOR.MINOR der CLI verfolgen, reicht das Anheften der CLI in der Regel nur aus:

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

Für strikte Reproduzierbarkeit über Patch-Ebenen hinweg auch Tools anheften:

uip tools install @uipath/orchestrator-tool@1.0.2

Weitere Informationen finden Sie unter Tools (Plugins) – Versionsauflösung .

Unterdrücken von interaktiven Prompts

Eine Handvoll uip -Befehle sind standardmäßig interaktiv, wenn standardout ein Tty ist:

• uip login – fordert zur Mandantenauswahl auf, wenn --tenant nicht übergeben wird.
• uip skills install/update/uninstall – fragt nach dem Ziel-Agent, wenn --agent nicht übergeben wird.
• uip completion – Fordert zur Bestätigung des Installationspfads auf.
• uip tools search – Fordert für eine Abfrage auf, wenn keine übergeben wird.

In CI können diese Prompts einen Auftrag zum Stillstand bringen. Vermeiden Sie sie, indem Sie immer die relevanten Flags übergeben (--tenant, --agent, --print/explizit Shell auf completion) oder indem Sie sicherstellen, dass „stdout“ kein Tty ist (die meisten CI-Ausführungen kümmern sich bereits um dies).

Deaktivieren der Telemetrie in CI

Anonyme Telemetrie wird standardmäßig an Application Insights von UiPath gesendet. Für Air-Gap- oder strikte Umgebungen:

export UIPATH_TELEMETRY_DISABLED=1

…oder über UIPATH_AI_CONNECTION_STRING auf Ihre eigene Instanz verweisen. Siehe Installieren von UiPath CLI – Telemetrie.

Siehe auch

• Exitcodes – die autoritative Tabelle.
• Ausgabeformate – der Umschlag und die vier Formate.
• Globale Optionen – --output, --output-filter, --log-level, --log-file.
• Authentifizierung – die drei Authentifizierungsflows, auf die im obigen Wiederholungsmuster verwiesen wird.
• CI/CD-Rezepte – vollständige plattformspezifische Pipelines.