Skriptien kirjoittaminen

Skripti on Python-logiikkaa, joka ajetaan palvelimella, sovelluksen sisällä. Se on oikea palanen kaikkeen, mikä ei ole näyttö eikä yksinkertainen kysely: datan synkronointi toisen järjestelmän kanssa, tunnuslukujen laskeminen uudelleen joka aamu, Excelin luonti ja lähettäminen sähköpostilla, API:n kautta ladatun tiedoston tarkistaminen.

Sama skripti voidaan laukaista kolmella tavalla — eikä koodi muutu:

Laukaisu	Miten se tapahtuu
Manuaalinen	Editorin painike Suorita nyt, valinnaisten argumenttien kanssa.
Cron	Ajastus (luku Ajastukset) — täsmällisinä kellonaikoina, väliajoin tai vahtimisikkunassa.
API	Sovelluksen API:n vaiheena — skripti saa pyynnön argumentit ja edellisen vaiheen tuloksen.

Tällä sivulla käytämme Asiakashallinta-sovelluksen skriptiä atualizar_indicadores, joka laskee CRM:n myynnin tunnusluvut uudelleen joka aamu.

#Missä skriptit asuvat

Sovelluksen sisällä skripteillä on oma osionsa sivupalkin puussa — ryhmä Skriptit. Jokainen skripti on puun solmu: nimen napsauttaminen avaa editorin työtilan välilehteen, ja vasemmalla oleva nuoli laajentaa solmun näyttämään sen Tiedostot, Riippuvuudet ja Ajastukset (tämän luvun seuraavat sivut).

Tarjolla on myös listanäkymä — sivu Skriptit — jossa on yksi rivi skriptiä kohti:

Sarake	Mitä se näyttää
Nimi	Skriptin nimi ja kuvaus.
Runtime	Suorituskieli (Python).
Tila	Aktiivinen tai Luonnos — vain aktiiviset ajetaan ajastuksesta.
Ajastukset	Montako ajastusta on, montako niistä on aktiivisia, ja Seuraava: seuraavan suunnitellun suorituksen päivämäärän kanssa.
Viimeisin suoritus	Tuoreimman suorituksen tila (Onnistui, Virhe, …) ja kellonaika.

#Skriptin luominen

1. Vie sivupalkin puussa hiiri ryhmän Skriptit rivin päälle ja napsauta painiketta + (Uusi skripti).

2. Täytä valintaikkuna Uusi skripti:

   Kenttä	Huomiot
   Nimi	Pakollinen. Esim. sincronizar-clientes. Tällä nimellä skriptiin viitataan ajastuksissa ja API:issa.
   Runtime	Kiinteä: Python. Palvelimella suoritetaan vain Pythonia.
   Kuvaus	Valinnainen — ”Mitä tämä skripti tekee?” näkyy listassa ja puussa.
   Aikaraja	30 sekuntia, 1 minuutti, 2 minuuttia, 5 minuuttia tai 10 minuuttia. Ylitettäessä prosessi lopetetaan ja suoritus merkitään aikakatkaistuksi.

3. Napsauta Luo skripti. Skripti syntyy aloituskoodin kanssa (sopimus näkyvissä, kommentteina) ja editori avautuu heti välilehteen.

#Sopimus: main(input)

Jokaisella skriptillä on aloitustiedosto main.py, jossa on funktio main. Alusta kutsuu sitä joka suorituksella, ja palautettu arvo on skriptin tulos:

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

Parametri input tuo aina kolme avainta:

Avain	Sisältö
input["args"]	Sanakirja, jossa ovat suorituksen argumentit — ne, jotka kirjoitit valintaikkunaan Suorita nyt, ne jotka on määritelty ajastuksessa, tai ne jotka API välitti. Arvot saapuvat tekstinä.
input["prev"]	Edellisen vaiheen tulos, kun skripti ajetaan API:n sisällä. Manuaalisissa ja ajastetuissa suorituksissa se on None.
input["context"]	Suorituksen metatiedot: skriptin nimi ja tunniste, laukaisu ("manual", "cron", "api" tai "catchup"), suorituksen numero ja kutsuja.

Tulosta koskevat säännöt:

• Sen on oltava JSON-muotoon sarjallistettavissa: sanakirjoja, listoja, tekstiä, numeroita, totuusarvoja tai None. Muun tyyppiset objektit kaatavat suorituksen.
• Tuloksen enimmäiskoko on 32 Mt.
• Kiinni ottamaton poikkeus päättää suorituksen tilaan Virhe, ja koko traceback jää lokeihin.

Kaikki, mitä tulostat — print-käskyllä tai SDK:n funktiolla log(...) — näkyy suorituksen lokeissa rivi riviltä. Datan käsittelyyn, HTTP-kutsuihin, salaisuuksiin, ilmoituksiin ja muuhun käytä SDK:ta api_manager, joka on kuvattu sivulla Skriptien SDK.

#Editori

Editori täyttää skriptin välilehden koko leveydeltään. Koodin yläpuolisessa palkissa näet aktiivisen tiedoston polun (aluksi main.py) ja sen vieressä tilapisteen — Tallennettu tai Tallentamattomia muutoksia. Koodille ei ole tallennuspainiketta: muutokset tallentuvat itsestään noin sekunnin kuluttua siitä, kun lopetat kirjoittamisen.

Palkin oikeassa reunassa ovat painikkeet:

Painike	Mitä se tekee
Suorita nyt (▶)	Tallentaa kaiken ja avaa manuaalisen suorituksen valintaikkunan.
Suoritukset	Avaa skriptin suoritushistorian.
Kehote LLM:lle	Avaa kopiointivalmiin tekstin, jossa on koko SDK:n sopimus, jotta voit pyytää skriptin tekoälyavustajalta — katso Skriptien SDK.
Suurenna editori	Editori täyttää koko ruudun; Esc tai Pienennä editori palauttaa normaalin.

Pythonia kirjoittaessasi editori täydentää automaattisesti: se ehdottaa SDK:n moduuleja ja funktioita (db, http, log, …), omia tiedostojasi ja skriptin ympäristöön asennettuja pip-paketteja, näyttää parametrien allekirjoituksen kutsua täyttäessäsi ja dokumentaation, kun viet hiiren nimen päälle.

#Suorittaminen käsin

1. Napsauta Suorita nyt (▶). Kaikki tallentamaton tallennetaan ensin.
2. Määritä valintaikkunassa tämän suorituksen argumentit (valinnainen): napsauta Lisää argumentti ja täytä Nimi (esim. clienteId) ja Arvo. Arvot saapuvat skriptille tekstinä, kohdassa input["args"].
3. Napsauta Suorita.

Editorin alapuolella oleva paneeli Suorituksen tulos näyttää heti:

• tilan — Onnistui tai Virhe — ja keston millisekunteina;
• funktion main palauttaman arvon JSON-muodossa;
• Lokit, joissa on jokainen rivi, jonka log(...) tai print kirjoitti.

Jos suoritus epäonnistuu, virheilmoitus ilmestyy tuloksen paikalle ja koko traceback jää lokeihin.

#Suoritushistoria

Napsauta editorin palkissa Suoritukset. Valintaikkuna listaa kaikki skriptin suoritukset, ja niitä voi suodattaa tilan, alkuperän, keston ja päivämäärän mukaan:

Sarake	Sisältö
Alkoi	Päivä ja kellonaika, jolloin suoritus alkoi.
Alkuperä	Manuaalinen, Cron, API tai Jälkisuoritus (ajastuksesta väliin jääneen ajon jälkikäteen tehty suoritus).
Tila	Katso taulukko alla.
Kesto	Millisekunteina.

Mahdolliset tilat:

Tila	Mitä se tarkoittaa
Onnistui	main palautti tuloksen ilman virhettä.
Virhe	Kiinni ottamaton poikkeus tai tulos, jota ei voi sarjallistaa.
Käynnissä	Suoritus ei ole vielä päättynyt.
Aikakatkaisu	Ylitti skriptin Aikarajan ja se lopetettiin.
Keskeytetty	Prosessi lopetettiin ennen loppua (esim. palvelimen pysäytys).
Ohitettu (päällekkäisyys)	Ajastus laukesi, kun edellinen suoritus oli vielä käynnissä — tämä ei ehtinyt ajoon lainkaan.

Napsauta rivillä Tiedot laajentaaksesi sen: näet Argumentit, joilla se ajettiin, palautetun Tuloksen, Virheen (jos sellainen oli) ja täydet Lokit.

#Aktiivinen vai luonnos

Skriptin paneelin otsikkorivillä on kytkin Aktiivinen. Skripti, jonka kytkin on pois päältä, on Luonnos:

• se ei aja ajastuksesta — suunnitellut kellonajat kirjataan tilaan Ohitettu, huomiona ”Skripti on luonnostilassa”;
• sen voi yhä suorittaa käsin editorissa, jotta voit testata rauhassa.

Näin kehitetään ilman kiirettä: kirjoita, testaa painikkeella Suorita nyt, ja kytke Aktiivinen päälle vasta kun skripti on valmis ajamaan itsekseen.

#Skriptin asetukset

Avaa Skriptin asetukset (skriptin toimintovalikosta puussa tai paneelin otsikkoriviltä) muuttaaksesi seuraavia:

Kenttä	Huomiot
Nimi	Nimi, jolla ajastukset ja API:t siihen viittaavat.
Versio	Näytetään siellä, missä tätä skriptiä käytetään toisen riippuvuutena (sovellus/skripti@versio).
Kuvaus	Vapaata tekstiä.
Aikaraja	Samat vaihtoehdot kuin luotaessa, 30 sekunnista 10 minuuttiin.

Runtime ei ole muokattavissa — se määritetään luotaessa.

#Usein kysyttyä

Miksi suoritus näkyy tilassa Aikakatkaisu? Skripti kesti kauemmin kuin määritetty Aikaraja. Nosta rajaa kohdassa Skriptin asetukset (enintään 10 minuuttia) tai jaa työ osiin — käsittele esimerkiksi pienempiä eriä suoritusta kohti.

Kirjoitin editorissa ja ajoin heti — ajoiko se vanhan version? Ei. Suorita nyt tallentaa ensin kaiken tallentamattoman; suoritus käyttää aina sitä, mikä on ruudulla.

Tulos palautuu oikein, mutta argumentit saapuvat ”väärin”? Argumentit saapuvat aina tekstinä. Argumentti limite = 10 saapuu muodossa "10" — muunna se koodissa: int(input["args"].get("limite", 0)).

Voinko säilyttää tilaa suoritusten välillä? Jokainen suoritus on erillinen prosessi — muuttujat eivät säily suorituksesta toiseen. Säilyttääksesi jotain kirjoita tiedosto skriptin kansioon (katso Riippuvuudet ja tiedostot) tai tallenna data tietolähteeseen.