Skrive skript

Et skript er logikk i Python som kjører på serveren, inne i appen. Det er den rette brikken for alt som verken er en skjerm eller en enkel spørring: synkronisere data med et annet system, regne ut indikatorer på nytt hver morgen, lage en Excel-fil og sende den på e-post, validere en fil som er lastet opp av et API.

Det samme skriptet kan utløses på tre måter — og koden endrer seg ikke:

Utløser	Slik skjer det
Manuell	Knappen Kjør nå i editoren, med valgfrie argumenter.
Cron	En tidsplan (kapittelet Tidsplaner) — på faste klokkeslett, med intervaller, eller i et overvåkingsvindu.
API	Som trinn i et API i appen — skriptet får argumentene fra forespørselen og resultatet fra det forrige trinnet.

Gjennom hele denne siden bruker vi skriptet atualizar_indicadores i appen Kundeadministrasjon, som regner ut de kommersielle indikatorene i CRM-et på nytt hver morgen.

#Hvor skriptene bor

Inne i appen har skriptene sin egen seksjon i sidetreet — gruppen Skript. Hvert skript er en node i treet: klikk på navnet, så åpnes editoren i en fane i arbeidsområdet, og pilen til venstre utvider noden og viser Filer, Avhengigheter og Tidsplaner som hører til det (de neste sidene i dette kapittelet).

Det finnes også en listevisning — siden Skript — med én linje per skript:

Kolonne	Hva den viser
Navn	Navnet og beskrivelsen av skriptet.
Runtime	Kjørespråket (Python).
Status	Aktiv eller Utkast — bare de aktive kjører etter tidsplan.
Tidsplaner	Hvor mange tidsplaner som finnes, hvor mange som er aktive, og Neste: med datoen for den neste planlagte kjøringen.
Siste kjøring	Statusen (Vellykket, Feil, …) og klokkeslettet for den siste kjøringen.

#Opprette et skript

1. I sidetreet holder du markøren over linjen til gruppen Skript og klikker på knappen + (Nytt skript).

2. Fyll ut modalen Nytt skript:

   Felt	Merknader
   Navn	Påkrevd. F.eks.: sincronizar-clientes. Det er med dette navnet skriptet refereres til i tidsplaner og API-er.
   Runtime	Fast: Python. Kjøring på serveren er bare Python.
   Beskrivelse	Valgfritt — «Hva gjør dette skriptet?» vises i listen og i treet.
   Tidsgrense	30 sekunder, 1 minutt, 2 minutter, 5 minutter eller 10 minutter. Når grensen overskrides, avsluttes prosessen og kjøringen merkes som tidsavbrudd.

3. Klikk på Opprett skript. Skriptet blir født med startkoden (kontrakten synlig, i kommentarer), og editoren åpnes med én gang i en fane.

#Kontrakten: main(input)

Hvert skript har en inngangsfil, main.py, med en funksjon main. Plattformen kaller den ved hver kjøring, og verdien som returneres er resultatet av skriptet:

def main(input):
    return {"ok": True}

Parameteren input inneholder alltid tre nøkler:

Nøkkel	Innhold
input["args"]	Ordbok med argumentene for kjøringen — de du skrev i modalen Kjør nå, de som er definert i tidsplanen, eller de API-et sendte med. Verdiene kommer som tekst.
input["prev"]	Resultatet fra det forrige trinnet, når skriptet kjører inne i et API. Ved manuelle og planlagte kjøringer er det None.
input["context"]	Metadata om kjøringen: navnet og identifikatoren til skriptet, utløseren ("manual", "cron", "api" eller "catchup"), nummeret på kjøringen, og hvem som kalte den.

Regler for resultatet:

• Det må være serialiserbart som JSON: ordbøker, lister, tekster, tall, booleaner eller None. Objekter av andre typer får kjøringen til å feile.
• Maksimal størrelse på resultatet er 32 MB.
• Et unntak som ikke fanges opp avslutter kjøringen med Feil, og hele sporingen (traceback) havner i loggene.

Alt du skriver ut — med print eller med log(...) fra SDK-en — vises i loggene for kjøringen, linje for linje. For å komme til data, HTTP-kall, hemmeligheter, varsler og mer, bruker du SDK-en api_manager, som er beskrevet på siden SDK-en for skript.

#Editoren

Editoren fyller fanen til skriptet i hele bredden. På linjen over koden ser du stien til den aktive filen (main.py til å begynne med) med en statusprikk ved siden av — Lagret eller Ulagrede endringer. Det finnes ingen knapp for å lagre koden: endringene lagrer seg selv omtrent ett sekund etter at du slutter å skrive.

Til høyre på linjen finner du knappene:

Knapp	Hva den gjør
Kjør nå (▶)	Lagrer alt og åpner dialogen for manuell kjøring.
Kjøringer	Åpner historikken over kjøringer for skriptet.
Prompt til LLM	Åpner en ferdig tekst du kan kopiere, med hele kontrakten til SDK-en, slik at du kan be en KI-assistent om skriptet — se SDK-en for skript.
Maksimer editoren	Editoren fyller hele skjermen; Esc eller Minimer editoren tar deg tilbake.

Mens du skriver Python, fullfører editoren automatisk: den foreslår modulene og funksjonene i SDK-en (db, http, log, …), dine egne filer og pip-pakkene som er installert i miljøet til skriptet, den viser signaturen til parameterne mens du fyller ut et kall, og dokumentasjon når du holder markøren over et navn.

#Kjøre for hånd

1. Klikk på Kjør nå (▶). Det som ikke er lagret ennå, lagres først.
2. I dialogen angir du argumentene for denne kjøringen (valgfritt): klikk på Legg til argument og fyll ut Navn (f.eks.: clienteId) og Verdi. Verdiene når skriptet som tekst, i input["args"].
3. Klikk på Kjør.

Panelet Resultatet av kjøringen, under editoren, viser med én gang:

• statusen — Vellykket eller Feil — og varigheten i millisekunder;
• verdien som main returnerte, formatert som JSON;
• Logger, med hver linje skrevet av log(...) eller print.

Hvis kjøringen feiler, vises feilmeldingen i stedet for resultatet, og hele sporingen havner i loggene.

#Historikken over kjøringer

Klikk på Kjøringer på linjen i editoren. Modalen lister opp alle kjøringene av skriptet, med filtre på status, opphav, varighet og dato:

Kolonne	Innhold
Start	Dato og klokkeslett da kjøringen begynte.
Opphav	Manuell, Cron, API eller Innhenting (kjøring som er hentet inn fra en tidsplan som ikke ble kjørt).
Status	Se tabellen nedenfor.
Varighet	I millisekunder.

De mulige statusene:

Status	Betyr
Vellykket	main returnerte et resultat uten feil.
Feil	Et unntak som ikke ble fanget opp, eller et resultat som ikke lot seg serialisere.
Kjører	Kjøringen er ikke ferdig ennå.
Tidsavbrudd	Den overskred Tidsgrensen til skriptet og ble avsluttet.
Avbrutt	Prosessen ble avsluttet før den var ferdig (f.eks. fordi serveren stoppet).
Hoppet over (overlapp)	En tidsplan utløste mens den forrige kjøringen fortsatt pågikk — denne kom aldri i gang.

Klikk på Detaljer på en linje for å utvide den: du ser Argumenter som den kjørte med, Resultat som ble returnert, Feil (hvis det var noen) og hele Logger.

#Aktiv eller utkast

I overskriften til skriptpanelet finnes en bryter Aktiv. Et skript med bryteren av står som Utkast:

• det kjører ikke etter tidsplan — de planlagte klokkeslettene registreres som Hoppet over, med merknaden «Skriptet er et utkast»;
• det kan fortsatt kjøres for hånd i editoren, så du kan teste i fred.

Det er måten å utvikle i ro på: skriv, test med Kjør nå, og slå først på Aktiv når skriptet er klart til å kjøre av seg selv.

#Innstillinger for skriptet

Åpne Innstillinger for skriptet (fra handlingsmenyen til skriptet i treet, eller fra overskriften i panelet) for å endre:

Felt	Merknader
Navn	Navnet som tidsplaner og API-er bruker for å referere til det.
Versjon	Vises der dette skriptet brukes som avhengighet for et annet (app/skript@versjon).
Beskrivelse	Fri tekst.
Tidsgrense	De samme alternativene som ved opprettelsen, fra 30 sekunder til 10 minutter.

Runtime vises ikke for redigering — den settes når skriptet opprettes.

#Vanlige spørsmål

Hvorfor står kjøringen som Tidsavbrudd? Skriptet brukte lengre tid enn den Tidsgrensen som er satt. Øk grensen i Innstillinger for skriptet (maksimum: 10 minutter) eller del opp arbeidet — behandle for eksempel mindre partier per kjøring.

Jeg skrev i editoren og kjørte med én gang — kjørte den gamle versjonen? Nei. Kjør nå lagrer først alt som ikke er lagret; kjøringen bruker alltid det som står på skjermen.

Resultatet kommer riktig ut, men argumentene kommer «feil»? Argumentene kommer alltid som tekst. Et argument limite = 10 kommer som "10" — konverter det i koden: int(input["args"].get("limite", 0)).

Kan jeg ta vare på tilstand mellom kjøringer? Hver kjøring er en isolert prosess — variabler overlever ikke fra den ene til den andre. For å ta vare på noe skriver du en fil i mappen til skriptet (se Avhengigheter og filer) eller lagrer dataene i en datakilde.