CLI-Automatisierung und Ausgabe

Im Terminal gibt die CLI übersichtliche Tabellen aus. Wird die Ausgabe in eine Pipe umgeleitet, liefert sie JSON. So funktioniert derselbe Befehl sowohl bei der interaktiven Nutzung als auch in der Automatisierung.

aiglot batches list                    # table on a terminal
aiglot batches list | jq '.data[0].id' # JSON when piped
aiglot batches list --output ndjson    # one object per line
aiglot account --json                  # explicit JSON

Fehler und wichtige Warnungen, etwa zu einer gekürzten Ergebnisseite, werden auf die Standardfehlerausgabe geschrieben. Die Standardausgabe kann daher sicher an ein anderes Programm weitergeleitet werden.

Warten, bis eine Übersetzung fertig ist

Erstellen Sie zuerst den Plan und prüfen Sie seinen Umfang, die Ausschlüsse und die ermittelten Kosten. Die CLI gibt einzelne Objekte direkt zurück: Lesen Sie .id, .status und .plan aus, nicht .data.id oder .data.status. Bei Listenbefehlen wird weiterhin ein data-Array verwendet.

set -euo pipefail

batch=$(aiglot batches create catalogue.csv --instruction "Translate into French" --json)
id=$(printf '%s' "$batch" | jq -er '.id')
printf '%s\n' "$batch" | jq '.plan'

Führen Sie den nächsten Block erst aus, wenn der Plan, die gewählte Standardqualität und die ermittelten Kosten freigegeben sind. Eine bereits erteilte Freigabe genügt, wenn sie diese Punkte abdeckt. Die Wartezeit ist auf 60 Abfragen begrenzt und endet bei completed, failed oder cancelled. Wird der Vorgang unterbrochen oder läuft das Zeitlimit ab, behalten Sie die Batch-ID und setzen Sie den Vorgang fort, ohne eine weitere Übersetzung zu erstellen.

aiglot batches approve "$id" --quality standard --json

for ((attempt = 0; attempt < 60; attempt++)); do
  status=$(aiglot batches get "$id" --timeout 15 --json | jq -er '.status')
  case "$status" in
    completed)
      aiglot batches download "$id" --output result.csv
      break
      ;;
    failed|cancelled)
      printf 'Batch %s ended with status %s.\n' "$id" "$status" >&2
      exit 1
      ;;
    awaiting_instructions|awaiting_approval)
      printf 'Batch %s needs a decision; inspect its plan before continuing.\n' "$id" >&2
      exit 2
      ;;
  esac
  if ((attempt == 59)); then
    printf 'Wait limit reached. Resume batch %s; do not create a duplicate.\n' "$id" >&2
    exit 1
  fi
  sleep 5
done

Dies sind alle Status, die eine Übersetzung melden kann, einschließlich der drei Status, mit denen sie endet. Jeder Status beantwortet dieselbe Frage: Wer wartet worauf?

Seitennummerierung

batches list und glossaries list verwenden Cursor-basierte Seitennummerierung. Übergeben Sie den next_cursor aus der vorherigen Antwort unverändert mit --cursor, oder lassen Sie --all alle Seiten abrufen, bis has_more den Wert false hat. Zur Sicherheit ist die Anzahl auf 200 Seiten begrenzt:

aiglot batches list --status completed --all
aiglot glossaries list --all --output ndjson

Bei --output ndjson gibt --all jede Zeile jeder Seite aus, sobald sie eintrifft. Im table- und json-Modus wird ein zusammengeführtes Ergebnis ausgegeben: has_more: false, next_cursor: null und ein pages_fetched-Zähler ersetzen request_id, da nach mehreren Anfragen keine einzelne Anfrage mehr angegeben werden kann.

Authentifizierung in CI

Erstellen Sie einen dedizierten API-Schlüssel mit minimalen Berechtigungen und speichern Sie ihn im Secret-Manager Ihres CI-Anbieters:

export AIGLOT_API_KEY="aig_live_…"
aiglot account --json

Die CLI prüft Zugangsdaten in dieser Reihenfolge: AIGLOT_API_KEY, Betriebssystem-Schlüsselbund und anschließend die geschützte Konfigurationsdatei.

Exit-Codes

Skripte sollten anhand des Exit-Codes oder von error.code in der strukturierten Fehlermeldung verzweigen, nicht anhand des Fehlertexts.

Wiederholungsversuche

Wiederholungsversuche erfolgen automatisch, aber nur, wenn sie sicher sind. Bei 429 wird jeder Befehl erneut versucht. Dabei wird Retry-After berücksichtigt und die Wartezeit begrenzt erhöht. Bei 408 und 5xx werden nur idempotente Anfragen erneut versucht (RFC 9110 §9.2.2): Lesezugriffe sowie glossaries replace und glossaries delete.

glossaries create, glossaries add, glossaries remove, batches rename und batches archive werden nach einem 5xx nicht erneut ausgeführt, da die Änderung bereits übernommen worden sein könnte und ein weiterer Versuch sie doppelt anwenden würde. Solche Fehler werden mit Exit-Code 1 an Ihr Skript zurückgegeben. Lesen Sie die Ressource erneut ein und entscheiden Sie selbst, ob Sie den Vorgang wiederholen möchten, statt blind einen weiteren Versuch zu starten.

Mit --no-retry legen Sie die Wiederholungsstrategie selbst fest. Mit --timeout <seconds> begrenzen Sie die Dauer einer einzelnen Anfrage (Standardwert: 60). Destruktive Befehle warten niemals unbegrenzt auf eine interaktive Eingabeaufforderung. Bei nicht interaktiver Nutzung muss --force angegeben werden.

Profile

Mit benannten Profilen können Sie die Zugangsdaten für verschiedene Arbeitsbereiche oder Umgebungen getrennt verwalten:

aiglot --profile client-a auth login --key "$CLIENT_A_KEY"
aiglot --profile client-a account
export AIGLOT_PROFILE=client-a

Umgebungsvariablen