Modèles de script

Cette page collecte les modèles qui facilitent la script uip — dans les pipelines shell, PowerShell et CI. Rien n’est spécifique à un seul outil ici; chaque modèle repose sur le contrat que le code de sortie et l'enveloppe JSON exposent de manière cohérente entre les commandes.

Valeurs par défaut utiles

Trois décisions de conception simplifient le script:

1. JSON est la sortie par défaut. Aucun --output json nécessaire, que vous vous trouviez dans un terminal ou un pipeline.
2. Stdout est JSON uniquement; tout le reste est stderr. Les journaux, les barres de progression et le texte d'erreur lisible par un humain sont dirigés vers stderr; la capture de stdout vous donne donc des données précises.
3. Les codes de sortie sont étroits et stables. Cinq valeurs (0, 1, 2, 3, 4) couvrent chaque mode d'échec documenté, plus 130 pour l'annulation de l'utilisateur. Les scripts peuvent se ramifier sans analyser les chaînes.

Options de shell strictes

Pour bash/zsh, commencez les scripts par:

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

• -e — abandonner sur n'importe quelle commande qui se termine non-zéro.
• -u — abandonner sur une variable non définie.
• -o pipefail — propagent un échec à partir de n'importe quelle étape d'un pipeline, et pas seulement à la dernière.

Pour PowerShell:

$ErrorActionPreference = 'Stop'

Arborescence selon les codes de sortie

La valeur Result de l'enveloppe correspond au code de sortie du processus. Branchez le code de sortie pour des décisions rapides; ouvrez l'enveloppe pour en savoir plus (voir Codes de sortie pour la table complète).

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

Lecture des valeurs hors de l'enveloppe

Utilisez --output-filter pour extraire des valeurs à la source, plutôt que des pipelines via jq:

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

--output plain renvoie la valeur à barres (sans guillemets) pour un résultat de filtre scalaire. Pour les tableaux et les objets, --output json conserve la structure:

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 vous préférez jq de bout en bout, capturez le JSON brut et la chaîne:

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

Les deux approches produisent la même valeur. --output-filter est plus rapide et se valide au moment de l’analyse du CLI; jq vous donne le JMESPath complet plus les constructions spécifiques à Jq comme [-1] (dernier élément) et to_entries.

Réauthentification en cas d’erreur d’authentification (sortie 2)

Les jetons d’accès ont une expiration. Dans un script de longue durée, le modèle est le suivant: exécuter la commande, revenir à uip login si le jeton est absent, réessayer une fois, puis échouer définitivement.

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

Limitez le nombre de tentatives: une seule tentative d’authentification gère l’expiration du jeton; d'autres tentatives masqueraient des informations d'identification mal configurées et des limites de taux de rupture.

Interrogation des opérations de longue durée

Certaines opérations se terminent de manière asynchrone côté Orchestrator:

• Exécution de la tâche: utilisez uip or jobs start --wait-for-completion pour que l’interrogation CLI vous corresponde. Le délai d’expiration par défaut est de 300 secondes, personnalisable avec --timeout. L'intervalle d'interrogation est de 5 secondes, personnalisable avec --poll-interval.
• Déploiement de la solution — uip solution deploy run interrogations en interne avec un délai d'expiration par défaut de 360 secondes.
• Exécution de test — uip tm testsets run lance l'exécution, renvoie une ExecutionId et se termine immédiatement avec 0. Pour bloquer jusqu'à la fin de l'exécution, chaînez uip tm wait (qui interroge et quitte 2 au moment du délai d'attente). Pour lire le verbe de réussite/d’échec après l’attente, inspectez Data.Failed dans uip tm report get. Consultez les ensembles de tests uip tm, les exécutions uip tm et uip tm attente.

Lorsque l'interrogation intégrée est trop approximative, ou lorsque l'état du terminal nécessite une gestion personnalisée, interrogez-vous:

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

Limitez toujours la boucle à temps - une tâche défaillante qui se termine dans une boucle en attente bloquera autrement pour toujours:

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

Pipelines idempotentes

De nombreuses commandes uip sont idempotentes par leur conception; leur réexécution avec les mêmes arguments renvoie la ressource existante ou ne fait rien:

• uip solution publish — la republication d'un package avec le même nom et la même version renvoie la version existante.
• uip tools install — une exception si l'outil est déjà installé.
• uip or processes create — échouera en cas de doublon du nom dans le dossier; utilisez uip or processes update-version ou uip or processes edit dans ce cas.
• uip resource assets deploy --from-file — mises à jour insérées par clé.

Combinez-les avec set -e pour créer des pipelines qui peuvent être réexécutés après un échec partiel sans étapes de nettoyage.

Séparer les données des journaux

Stdout correspond à JSON. Sterr, c’est tout le reste. Redirigez-les indépendamment:

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

Ceci est particulièrement important dans CI: une tâche qui imprime les indicateurs de progression ou la sortie npm en ligne avec le flux de données produira du JSON managé pour les étapes ultérieures pouvant être utilisées.

Gérer les résultats vides

Une commande qui réussit avec zéro ligne dans Data quitte 0 — la requête de liste a fonctionné, mais rien ne correspond. Détectez ceci avec --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

Aucune correspondance de modèle en cas d’absence d’une Name dans la sortie de la table; ce n'est pas un format analysable.

Épingler des versions dans CI

Les pipelines reproductibles nécessitent d'épingler à la fois la CLI et (éventuellement) les outils. Étant donné que les versions d'outils suivent la ligne MAJOR.MINIOR de la CLI par défaut, épingler la CLI seule suffit généralement:

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

Pour une reproductibilité stricte entre les niveaux de correctif, épinglez également les outils:

uip tools install @uipath/orchestrator-tool@1.0.2

Voir Outils ( plugins ) — résolution de version pour les détails.

Supprimer les invites interactives

Certaines commandes uip sont interactives par défaut lorsque stdout est un Tty:

• uip login — invite à la sélection du locataire si --tenant n'est pas défini.
• uip skills install/update/uninstall — invite l'agent cible si --agent n'est pas défini.
• uip completion — invite à confirmer le chemin d'installation.
• uip tools search — invite à effectuer une requête si aucune n'est réussie.

Dans CI, ces invites peuvent suspendre une tâche. Évitez-les en transmettant toujours les indicateurs pertinents (--tenant, --agent, --print/explicity shell sur completion) ou en vous assurant que stdout n’est pas un TType (la plupart des exécuteurs CI le prennent déjà en charge).

Désactivation de la télémétrie dans CI

La télémétrie anonyme est envoyée par défaut à l'application Insights d'UiPath. Pour les environnements physiquement isolés ou strictes:

export UIPATH_TELEMETRY_DISABLED=1

…ou pointez-le sur votre propre instance via UIPATH_AI_CONNECTION_STRING. Voir Installation de la UiPath CLI — Télémétrie.

Voir également

• Codes de sortie — la table d'autorité.
• Formats de sortie — l'enveloppe et les quatre formats.
• Options globales — --output, --output-filter, --log-level, --log-file.
• Authentification — les trois flux d'authentification référencés dans le modèle de réessai ci-dessus.
• Formules CI/CD — Pipelines spécifiques à la plateforme complète.