Skripte und CI

Nach dieser Anleitung läuft die CLI in einer Pipeline ohne Profildatei, Ihr Skript reagiert auf Exit-Codes statt auf Text, holt Listen vollständig, begrenzt Wartezeiten und wiederholt verändernde Aufrufe, ohne einen Vorgang doppelt anzustoßen.

Schritte#

1. Legen Sie Adresse und Schlüssel als Geheimnisse Ihrer CI ab und reichen Sie sie als SZENERA_BASE_URL und SZENERA_API_KEY in den Lauf. Beide Variablen tragen zusammen ein vollständiges Profil; eine Datei auf der Platte ist nicht nötig, und das Profil ist nicht schreibgeschützt.

2. Rufen Sie die CLI direkt über die gebaute Datei auf, nie über pnpm run — sonst sieht Ihr Skript für jeden Fehler den Code 1:

   export SZENERA_BASE_URL="https://<basis-adresse>"
   export SZENERA_API_KEY="$CI_GEHEIMNIS_SIGNAGE"
   szenera() { node packages/cli/dist/main.js "$@"; }
   

3. Prüfen Sie am Anfang jeder Pipeline die Umgebung und den Ausweis — zwei Aufrufe, die Netz und Schlüssel trennen:

   szenera health --json > /dev/null || { echo "Umgebung nicht bereit"; exit 1; }
   szenera whoami --json | jq -r '.tenantId'
   

4. Werten Sie den Exit-Code aus, nicht die Meldung. Die Standardausgabe trägt im Fehlerfall nichts, deshalb darf sie gefahrlos in eine Datei gehen:

   szenera asset upload --file=plakat.png --json > ergebnis.json
   case $? in
     0)     echo "fertig: $(jq -r '.id' ergebnis.json)" ;;
     8|10)  sleep 30; echo "später erneut versuchen" ;;   # Bremse oder kein Netz
     11)    echo "Vorgang endete rot — Befund lesen"; exit 1 ;;
     12)    echo "Zeitlimit — erst nachsehen, nicht blind wiederholen"; exit 1 ;;
     *)     exit 1 ;;
   esac
   

5. Verarbeiten Sie die JSON-Ausgabe mit jq. Listen tragen items und, solange Seiten folgen, nextCursor:

   szenera device list --json | jq -r '.items[] | select(.status=="active") | .id'
   

Optionen#

Listen vollständig holen. --all folgt allen Seiten, bis keine mehr kommt, und liefert eine zusammengehängte Liste ohne nextCursor. Bei großen Beständen kombinieren Sie es mit --limit=200, dem Deckel je Seite:

szenera scene list --all --limit=200 --json | jq -r '.items[].id'

Wartezeiten begrenzen. Befehle, die auf einen Vorgang warten — asset upload, asset reprocess, device screenshot, device send-command --wait —, nehmen --timeout=<dauer> (90s, 20m, 2h oder eine Zahl in Sekunden) und teils --interval=<dauer>. --no-wait stößt nur an und kommt sofort zurück, ohne den Ausgang zu kennen. Exit 12 heißt in jedem Fall: Ausgang unbekannt, der Vorgang läuft womöglich weiter.

Wiederholungen absichern. Beim Notausgang api post|put|patch|delete erzeugt die CLI je Aufruf einen frischen Idempotenz-Schlüssel; --idempotency-key=<schluessel> ist nur nötig, um eine abgebrochene Wiederholung fortzusetzen — dann mit demselben Wert wie beim ersten Versuch. Befehle, die von sich aus idempotent sind, sagen es in ihrer Hilfe: player set-program zweimal zu senden ist kein zweiter Vorgang.

szenera api post /v1/playlists @playlist.json --idempotency-key="import-${CI_LAUF_ID}"

Schutz vor Unwiderruflichem. Befehle, die etwas Unumkehrbares tun, verlangen --yes und brechen ohne die Flagge mit Exit 1 ab — asset purge, asset delete, scene delete, api-key revoke und weitere; szenera <befehl> --help nennt die Flagge. Für Profile in einer Datei bleibt readOnly: true der Riegel: Ein verändernder Befehl bricht dann mit Exit 2 ab, bevor ein Netzpaket entsteht. Ein Profil allein aus Umgebungsvariablen hat diesen Riegel nicht.

Ergebnis prüfen#

• szenera health und szenera whoami laufen am Anfang der Pipeline mit Exit 0; whoami nennt die erwartete Organisation unter tenantId.
• Ein absichtlich falscher Aufruf (szenera device list --state=active) endet mit Exit 1 und einer Meldung auf der Fehlerausgabe; die umgeleitete Datei bleibt leer.
• Nach einem Upload zeigt szenera asset get <ast_…> --json den Zustand ready.

Wenn etwas nicht klappt#

Weiterführendes#

• Ausgabe als JSON und Exit-Codes
• Profile und Ausweis
• Idempotenz von Anfang an