Skriva skript

Ett skript är logik i Python som körs på servern, inne i appen. Det är rätt verktyg för allt som varken är en skärm eller en enkel fråga: synkronisera data med ett annat system, räkna om nyckeltal varje morgon, skapa en Excel-fil och skicka den med e-post, validera en fil som laddats upp via ett API.

Samma skript kan utlösas på tre sätt — och koden ändras inte:

Utlösare	Hur det går till
Manuell	Knappen Kör nu i editorn, med valfria argument.
Cron	Ett schema (kapitlet Scheman) — på bestämda tider, med jämna mellanrum, eller i ett bevakningsfönster.
API	Som steg i ett API i appen — skriptet får anropets argument och resultatet från föregående steg.

Genom hela den här sidan använder vi skriptet atualizar_indicadores i appen Kundhantering, som räknar om CRM:ets kommersiella nyckeltal varje morgon.

#Var skripten bor

Inne i appen har skripten sin egen sektion i trädet i sidopanelen — gruppen Skript. Varje skript är en nod i trädet: att klicka på namnet öppnar editorn i en flik på arbetsytan, och pilen till vänster fäller ut noden så att du ser dess Filer, Beroenden och Scheman (följande sidor i det här kapitlet).

Det finns också en listvy — sidan Skript — med en rad per skript:

Kolumn	Vad den visar
Namn	Skriptets namn och beskrivning.
Runtime	Körspråket (Python).
Status	Aktivt eller Utkast — bara de aktiva körs enligt schema.
Scheman	Hur många scheman som finns, hur många som är aktiva, och Nästa: med datum för nästa planerade körning.
Senaste körningen	Status (Lyckades, Fel, …) och tidpunkten för den senaste körningen.

#Skapa ett skript

1. Håll muspekaren över raden för gruppen Skript i trädet i sidopanelen och klicka på knappen + (Nytt skript).

2. Fyll i dialogrutan Nytt skript:

   Fält	Anteckningar
   Namn	Obligatoriskt. T.ex.: synkronisera-kunder. Det är med det här namnet skriptet refereras i scheman och API:er.
   Runtime	Fast: Python. Körning på servern sker bara i Python.
   Beskrivning	Valfritt — ”Vad gör det här skriptet?” visas i listan och i trädet.
   Tidsgräns	30 sekunder, 1 minut, 2 minuter, 5 minuter eller 10 minuter. När gränsen överskrids avslutas processen och körningen markeras som timeout.

3. Klicka på Skapa skript. Skriptet föds med startkod (kontraktet framför dig, i kommentarer) och editorn öppnas direkt i en flik.

#Kontraktet: main(input)

Varje skript har en ingångsfil, main.py, med en funktion main. Plattformen anropar den vid varje körning, och det returnerade värdet är skriptets resultat:

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

Parametern input har alltid tre nycklar:

Nyckel	Innehåll
input["args"]	Ordlista med körningens argument — de du skrev i dialogrutan Kör nu, de som definierats i schemat, eller de som API:et skickade med. Värdena kommer som text.
input["prev"]	Resultatet från föregående steg, när skriptet körs inuti ett API. Vid manuella och schemalagda körningar är det None.
input["context"]	Metadata om körningen: skriptets namn och identifierare, utlösaren ("manual", "cron", "api" eller "catchup"), körningens nummer, och vem som anropade.

Regler för resultatet:

• Det måste vara serialiserbart som JSON: ordlistor, listor, texter, tal, booleaner eller None. Objekt av andra typer får körningen att misslyckas.
• Resultatets maxstorlek är 32 MB.
• Ett ofångat undantag avslutar körningen med Fel, med hela traceback:en i loggarna.

Allt du skriver ut — med print eller med SDK:ns log(...) — dyker upp i körningens loggar, rad för rad. För att komma åt data, HTTP-anrop, hemligheter, aviseringar och mer använder du SDK:n api_manager, som beskrivs på sidan Skriptens SDK.

#Editorn

Editorn upptar skriptets flik i hela dess bredd. I raden ovanför koden ser du sökvägen till den aktiva filen (main.py till att börja med) med en statuspunkt bredvid — Sparat eller Osparade ändringar. Det finns ingen knapp för att spara koden: ändringarna sparas av sig själva ungefär en sekund efter att du slutat skriva.

Till höger i raden finns knapparna:

Knapp	Vad den gör
Kör nu (▶)	Sparar allt och öppnar dialogen för manuell körning.
Körningar	Öppnar skriptets körningshistorik.
Prompt för LLM	Öppnar en färdig text att kopiera med hela SDK-kontraktet, för att be en AI-assistent om skriptet — se Skriptens SDK.
Maximera editorn	Editorn tar upp hela skärmen; Esc eller Minimera editorn återgår till det normala.

Medan du skriver Python kompletterar editorn automatiskt: den föreslår SDK:ns moduler och funktioner (db, http, log, …), dina egna filer och de pip-paket som är installerade i skriptets miljö, visar parametrarnas signatur medan du fyller i ett anrop, och dokumentation när du hovrar över ett namn.

#Köra för hand

1. Klicka på Kör nu (▶). Det som är osparat sparas först.
2. Ange den här körningens argument i dialogen (valfritt): klicka på Lägg till argument och fyll i Namn (t.ex.: kundId) och Värde. Värdena når skriptet som text, i input["args"].
3. Klicka på Kör.

Panelen Körningens resultat, nedanför editorn, visar direkt:

• statusen — Lyckades eller Fel — och varaktigheten i millisekunder;
• värdet som main returnerade, formaterat som JSON;
• Loggarna, med varje rad som skrivits av log(...) eller print.

Om körningen misslyckas visas felmeddelandet i resultatets ställe, och hela traceback:en hamnar i loggarna.

#Körningshistoriken

Klicka på Körningar i editorns rad. Dialogrutan listar alla skriptets körningar, med filter för status, utlösare, varaktighet och datum:

Kolumn	Innehåll
Start	Datum och tid då körningen började.
Utlösare	Manuell, Cron, API eller Ikappkörning (en körning som tagits igen från ett schema som blev ogjort).
Status	Se tabellen nedan.
Varaktighet	I millisekunder.

Möjliga statusar:

Status	Betyder
Lyckades	main returnerade ett resultat utan fel.
Fel	Ett ofångat undantag, eller ett resultat som inte går att serialisera.
Körs	Körningen är ännu inte klar.
Timeout	Skriptets Tidsgräns överskreds och körningen avslutades.
Avbruten	Processen avslutades i förtid (t.ex.: servern stoppades).
Överhoppad (överlappning)	Ett schema utlöste medan föregående körning fortfarande pågick — den här hann aldrig köras.

Klicka på Detaljer på en rad för att fälla ut den: du ser Argumenten den kördes med, Resultatet som returnerades, Felet (om det blev något) och hela Loggarna.

#Aktivt eller utkast

I skriptpanelens rubrik finns ett reglage, Aktivt. Ett skript med reglaget avstängt hamnar i Utkast:

• det körs inte enligt schema — de planerade tiderna registreras som Överhoppad, med noteringen ”Skriptet är ett utkast”;
• det går fortfarande att köra för hand i editorn, så att du kan testa i lugn och ro.

Det är sättet att utveckla utan stress: skriv, testa med Kör nu, och slå på Aktivt först när skriptet är redo att köra på egen hand.

#Skriptets inställningar

Öppna Skriptets inställningar (i skriptets åtgärdsmeny i trädet, eller via panelens rubrik) för att ändra:

Fält	Anteckningar
Namn	Namnet som scheman och API:er refererar skriptet med.
Version	Visas överallt där det här skriptet används som beroende till ett annat (app/skript@version).
Beskrivning	Fritext.
Tidsgräns	Samma alternativ som vid skapandet, från 30 sekunder till 10 minuter.

Runtime går inte att redigera — det bestäms när skriptet skapas.

#Vanliga frågor

Varför visas körningen som Timeout? Skriptet tog längre tid än den Tidsgräns som angetts. Höj gränsen under Skriptets inställningar (max: 10 minuter) eller dela upp arbetet — bearbeta till exempel mindre satser per körning.

Jag skrev i editorn och körde direkt — kördes den gamla versionen? Nej. Kör nu sparar först allt som är osparat; körningen använder alltid det som står på skärmen.

Resultatet blir rätt men argumenten kommer ”fel”? Argumenten kommer alltid som text. Ett argument limite = 10 kommer som "10" — konvertera i koden: int(input["args"].get("limite", 0)).

Kan jag spara tillstånd mellan körningar? Varje körning är en isolerad process — variabler överlever inte från den ena till den andra. För att spara något varaktigt, skriv en fil i skriptets mapp (se Beroenden och filer) eller spara data i en datakälla.