CLI-automatisering en uitvoer

De CLI toont leesbare tabellen in een terminal en JSON wanneer de uitvoer wordt doorgestuurd. Zo werkt dezelfde opdracht zowel interactief als in automatisering.

aiglot batches list                    # tabel in een terminal
aiglot batches list | jq '.data[0].id' # JSON bij doorsturen
aiglot batches list --output ndjson    # één object per regel
aiglot account --json                  # expliciet JSON

Fouten gaan naar standaardfout, net als waarschuwingen die de aanroeper moet kunnen zien, bijvoorbeeld wanneer een pagina met resultaten is afgekapt. Standaarduitvoer kan daardoor veilig naar een ander programma worden doorgestuurd.

Wachten tot een vertaling klaar is

Maak eerst het plan en controleer de omvang, uitsluitingen en berekende kosten. De CLI geeft afzonderlijke objecten rechtstreeks terug: lees .id, .status en .plan, niet .data.id of .data.status. Opdrachten voor lijsten gebruiken nog steeds een data-array.

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'

Voer het volgende blok pas uit nadat het plan, de geselecteerde Standard-kwaliteit en de berekende kosten zijn goedgekeurd. Bestaande goedkeuring volstaat als die hierop van toepassing is. Er wordt maximaal 60 keer gepolld. Het wachten stopt bij de status completed, failed of cancelled. Wordt het proces onderbroken of loopt het vast door een time-out, bewaar dan de batch-ID en hervat die batch zonder een nieuwe vertaling te starten.

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 is geëindigd met status %s.\n' "$id" "$status" >&2
      exit 1
      ;;
    awaiting_instructions|awaiting_approval)
      printf 'Voor batch %s is een beslissing nodig; controleer het plan voordat je verdergaat.\n' "$id" >&2
      exit 2
      ;;
  esac
  if ((attempt == 59)); then
    printf 'Wachtlimiet bereikt. Hervat batch %s; maak geen duplicaat aan.\n' "$id" >&2
    exit 1
  fi
  sleep 5
done

Dit zijn alle statussen die een vertaling kan melden, waaronder de drie eindstatussen. Ze geven allemaal antwoord op dezelfde vraag: wie wacht, en waarop?

Paginering

batches list en glossaries list gebruiken cursors. Geef de next_cursor uit het vorige antwoord ongewijzigd mee met --cursor, of laat --all de cursor volgen tot has_more false is (met een maximum van 200 pagina’s als extra begrenzing):

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

Met --output ndjson geeft --all elke rij van elke pagina weer zodra die binnenkomt. In de modi table en json geeft de opdracht één gecombineerd resultaat weer met has_more: false, next_cursor: null en een aantal opgehaalde pagina’s in pages_fetched in plaats van request_id, omdat er geen enkele aanvraag kan worden vermeld wanneer er meerdere zijn uitgevoerd.

Verificatie in CI

Maak een API-sleutel met alleen de minimaal benodigde rechten en sla deze op in de geheimenbeheerder van de CI-provider:

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

De CLI controleert de referenties in deze volgorde: AIGLOT_API_KEY, de OS-sleutelhanger en daarna het beveiligde configuratiebestand.

Afsluitcodes

Scripts moeten beslissingen baseren op de afsluitcode of de gestructureerde error.code, niet op de tekst van de foutmelding.

Nieuwe pogingen

Opnieuw proberen gebeurt automatisch, maar alleen als dat veilig is. 429 wordt bij elke opdracht opnieuw geprobeerd, met inachtneming van Retry-After en begrensde wachttijden. 408 en 5xx worden alleen opnieuw geprobeerd voor verzoeken die idempotent zijn (RFC 9110 §9.2.2): leesverzoeken, glossaries replace en glossaries delete.

glossaries create, glossaries add, glossaries remove, batches rename en batches archive worden niet opnieuw geprobeerd na een 5xx, omdat de wijziging mogelijk al is doorgevoerd en een tweede poging deze dubbel zou toepassen. Zulke fouten worden aan je script gemeld met afsluitcode 1. Lees de bron opnieuw uit en bepaal zelf of je het opnieuw probeert, in plaats van blind opnieuw te proberen.

Gebruik --no-retry als de aanroeper het beleid voor nieuwe pogingen bepaalt, en --timeout <seconds> (standaard 60) om de duur van één verzoek te begrenzen. Bij destructieve opdrachten wordt nooit eindeloos op een interactieve prompt gewacht: bij niet-interactief gebruik moet --force worden meegegeven.

Profielen

Gebruik benoemde profielen om referenties voor verschillende werkruimten of omgevingen gescheiden te houden:

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

Omgevingsvariabelen