Skriptien SDK

Skriptin sisällä koko sovellus on yhden import-lauseen päässä. SDK:n nimi on api_manager, ja se tuodaan moduuli kerrallaan:

from api_manager import db, http, log, files, secrets, notify, workflow, reports

Nämä kahdeksan nimeä ovat SDK:n koko julkinen pinta — mitä täällä ei ole, sitä ei suorituksessa ole olemassa:

Moduuli	Mihin
db	Sovelluksen tietolähteiden kysely (Oracle, PostgreSQL, MySQL/MariaDB, SQL Server, …).
http	HTTP-pyynnöt ulkoisiin palveluihin, automaattisella JSONilla.
log	Rivien kirjoittaminen suorituksen lokeihin.
files	API:in upload-lähetettyjen tiedostojen lukeminen.
secrets	Sovelluksen salaisuuksien lukeminen, palvelimella purettuina.
notify	Sovelluksen sisäiset ilmoitukset ja sähköpostit sovelluksen käyttäjille.
workflow	Prosessien käynnistäminen, odotusten herättäminen ja ihmistehtävien ratkaiseminen.
reports	Sovelluksen raporttien luonti PDF- tai Excel-muodossa.

Editori täydentää tämän kaiken automaattisesti — nimet, parametrit ja kunkin funktion dokumentaatio ilmestyvät kirjoittaessasi.

#db — sovelluksen tietolähteet

Sovellukseen määritettyihin tietolähteisiin viitataan nimellä. Kaksi funktiota:

from api_manager import db

crm = db("Dados CRM")

linhas = crm.query(          # lista dictejä (sarake -> arvo)
    "select id, nome from contas where cidade = ?", ["Lisboa"]
)
conta = crm.query_one(       # ensimmäinen rivi, tai None
    "select * from contas where id = ?", [42]
)

params on paikkasidonnainen lista. Placeholderit ovat tietolähteen moottorin omat:

Moottori	Placeholderit	Esimerkki
PostgreSQL	$1, $2, …	where id = $1
MySQL / MariaDB	?	where id = ?
Oracle	:1, :2, …	where id = :1

Jos tietolähdettä ei ole olemassa, kutsu heittää virheen (ja suoritus päättyy tilaan Virhe, jos et ota sitä kiinni).

#http — pyynnöt ulkoisiin palveluihin

Viisi verbiä, kaikissa automaattinen JSON — dict- tai lista-body lähtee JSONina, ja JSON-vastaus saapuu jo purettuna:

from api_manager import http, log

r = http.get("https://api.exemplo.com/clientes")
# r = {"status": int, "ok": bool, "body": <purettu json tai teksti>}
if r["ok"]:
    log("vastaanotettu", len(r["body"]), "asiakasta")

r = http.post(
    "https://api.exemplo.com/leads",
    body={"nome": "Vininha & Filhos", "origem": "keplin"},
    headers={"Authorization": "Bearer abc123"},
)

Olemassa ovat myös http.put(url, body, headers), http.patch(url, body, headers) ja http.delete(url, headers). r["ok"] on tosi 2xx-vastauksille — 404 tai 500 ei heitä poikkeusta, tarkista tila itse.

#log — suorituksen lokit

from api_manager import log

log("käsitellään", 42, {"fase": "inicial"})

Se hyväksyy useita argumentteja, kuten print — ja jokainen kutsu on rivi suorituksen lokeissa, näkyvissä paneelissa Suorituksen tulos ja historiassa Suoritukset. Klassinen print kaapataan myös, mutta log on SDK:n kanoninen muoto.

#files — upload-lähetetyt tiedostot

Kun sovelluksen API:lla on Upload-tyyppinen argumentti, asiakas lähettää tiedoston ja skripti saa sen kohdassa input["args"] handlena — tavut ovat levyllä, eivät muistissa. Moduuli files operoi tällä handlella:

from api_manager import files


def main(input):
    f = input["args"]["ficheiro"]      # uploadin handle
    texto = files.read_text(f)         # str (utf-8)
    dados = files.read(f)              # bytes
    caminho = files.path(f)            # absoluuttinen polku levyllä
    files.save(f, "ultimo-recebido.csv")   # kopioi skriptin kansioon
    return {"nome": f["filename"], "tamanho": f["size"]}

Handle tuo mukanaan filename, mimeType ja size — hyödyllisiä validointiin ennen käsittelyä.

#secrets — sovelluksen salaisuudet

Tokenit ja avaimet talletetaan sovelluksen sivulle Salaisuudet (sivupalkin puu, App-ryhmä), salattuina. Skripti lukee ne avaimella:

from api_manager import secrets

token = secrets.get("STRIPE_KEY")   # -> str | None
if token is None:
    raise RuntimeError("Salaisuutta STRIPE_KEY ei ole määritetty tässä sovelluksessa.")

Arvo puretaan palvelimella, suorituksen hetkellä — se ei koskaan näy selaimessa eikä jää koodiin.

#notify — ilmoitukset ja sähköpostit

Sovelluksella on kaksi kiinteää kanavaa — yksi sovelluksen sisäinen ja yksi sähköposti — jotka otetaan käyttöön sovelluksen Ilmoitukset-asetuksissa (siellä asuvat SMTP-määritys ja lähettäjä). users ovat sovelluksen käyttäjien käyttäjätunnuksia; roles laajenevat kaikkiin roolin jäseniin.

Sovelluksen sisällä, reaaliajassa:

from api_manager import notify

r = notify.send(
    "Raportti valmis",
    subtitle="Kuukausiraportit",
    body="Kuukausiraportti on saatavilla.",
    users=["joao"],
    roles=None,
    data={"url": "/relatorios/42"},
)
# r = {"recipients": int, "delivered": int}

delivered laskee reaaliajassa toimitetut, niille jotka ovat linjoilla; loput jäävät saapuneisiin ja saavat ilmoituksen sisään tullessaan.

Sähköposti:

r = notify.email(
    "Varastohälytys",
    to=["chefe@empresa.pt"],      # vapaat osoitteet
    users=None,
    roles=["admin"],              # ja/tai sovelluksen käyttäjät ja roolit
    text="Varasto alle minimin.",
    html=None,
)
# r = {"accepted": [sähköpostit], "skipped": [käyttäjätunnukset ilman sähköpostia]}

SMTP-lähetys tapahtuu palvelimella asynkronisesti — skripti ei jää odottamaan. attachments hyväksyy liitteet, joiden sisältö on base64-muodossa (katso alta reports tyypillistä tapausta varten).

#workflow — sovelluksen prosessit

Skripti voi käynnistää prosessin, herättää tapahtumaa odottavat ja ratkaista ihmistehtäviä. Prosessiin viitataan nimellä (tai pysyvällä tunnisteella); key on sen tietueen avain, jota prosessi koskee:

from api_manager import workflow

r = workflow.start("Aprovação de despesa", 42, data={"valor": 1200})
# r = {"instanceId": int}

r = workflow.signal("visto", key=42)
# r = {"woken": int}

abertas = workflow.tasks("joao")
# kyseisen sovelluskäyttäjän avoimet tehtävät, mahdollisine päätöksineen

r = workflow.complete(task=17, outcome="aprovar", as_user="joao",
                      data={"nota": "ok"})
# r = {"ok": bool}

Säännöt, joilla on väliä:

• workflow.start palaa heti kun moottori saapuu ensimmäiseen odotukseen — se ei koskaan jää odottamaan prosessin päättymistä.
• workflow.signal ilman key-arvoa herättää kaikki kyseisessä tapahtumassa pysähtyneet prosessit; {"woken": 0} ei ole virhe — ketään ei ehkä ollut odottamassa.
• workflow.complete-kutsussa as_user on pakollinen (päättäjä jää historiaan) ja tehtävän on oltava osoitettu sille käyttäjälle. outcome-arvot ovat tehtäväsolmun lopputulokset — samat, jotka ihminen näkee painikkeina. Älä keksi nimiä.

#reports — sovelluksen raporttien luonti

Dokumentti luodaan palvelimella, sovelluksen datalla, olemassa olevasta raportista:

from api_manager import notify, reports

r = reports.render("Facturas do mês", {"mes": "2026-03"})
# r = {"filename", "pages", "format", "mime", "bytes", "base64"}

notify.email(
    "Maaliskuun laskut",
    to=["financeiro@empresa.pt"],
    text="Liitteenä.",
    attachments=[{"filename": r["filename"], "content": r["base64"]}],
)

Kolmas, valinnainen argumentti on muoto: "pdf" (oletus) tai "xlsx". Parametrit ovat ne, jotka raportti määrittelee. Tuloksessa bytes on valmis levylle kirjoitettavaksi ja base64 valmis sähköpostin liitteeksi.

#Kokonainen esimerkki

Asiakashallinta-sovelluksen skriptin atualizar_indicadores tapaan — lukee pipelinen, kirjoittaa hyödyllisiä lokeja ja varoittaa, kun päätöksiä on lähellä:

from datetime import date, timedelta

from api_manager import db, log, notify


def main(input):
    crm = db("Dados CRM")

    abertas = crm.query_one(
        "select count(*) as n, coalesce(sum(valor), 0) as total "
        "from oportunidades where fase not in ('fechada_ganha', 'fechada_perdida')"
    )

    limite = (date.today() + timedelta(days=7)).isoformat()
    fechos = crm.query(
        "select titulo, data_fecho from oportunidades "
        "where fase not in ('fechada_ganha', 'fechada_perdida') "
        "and data_fecho <= ? order by data_fecho",
        [limite],
    )

    log("pipeline:", abertas["n"], "myyntimahdollisuutta /", abertas["total"], "EUR")
    if fechos:
        notify.send(
            "Päätöksiä tällä viikolla",
            body=f"{len(fechos)} myyntimahdollisuutta, joiden päätös on viimeistään {limite}.",
            roles=["comercial"],
        )

    return {
        "oportunidades_abertas": abertas["n"],
        "valor_pipeline": abertas["total"],
        "fechos_proximos_7_dias": len(fechos),
    }

#Rajat ja hyvät käytännöt

• main-funktion tuloksen on oltava JSON-muotoon sarjallistettavissa; enintään 32 Mt.
• Jokainen suoritus noudattaa skriptin Aikarajaa (30 sekunnista 10 minuuttiin) — sen ylittyessä prosessi lopetetaan ja tilaksi jää Aikakatkaisu.
• Suoritukset ovat erillisiä: älä nojaa edellisen suorituksen muuttujiin. Säilytä data skriptin kansion tiedostoissa tai tietolähteessä.
• Tee log(...) jokaisessa olennaisessa vaiheessa — sitä luet, kun jokin pettää sunnuntaina klo 7.00.
• Ota kiinni korjattavissa olevat virheet ja kirjaa ne; anna kohtalokkaiden nousta — kiinni ottamaton poikkeus merkitsee suorituksen tilaan Virhe, ja juuri sen haluat nähdä historiassa, kun jokin on oikeasti pielessä.
• Älä tulosta salaisuuksia, ja lue ne aina moduulista secrets — älä koskaan kirjoita niitä koodiin.

#Usein kysyttyä

from api_manager import db epäonnistuu omalla koneellani. Se on odotettua: moduuli api_manager on olemassa vain alustalla suoritettaessa — siellä se injektoidaan. Editorissa sinulla on SDK:n täysi automaattitäydennys; skriptin kansiossa näkyvä tiedosto api_manager.py on olemassa vain sitä varten.

db("nimi") sanoo, ettei tietolähdettä ole olemassa. Nimen on oltava täsmälleen sovelluksen tietolähteen nimi (esim. Dados CRM, isoine kirjaimineen ja välilyönteineen). Katso lista puun osiosta Tietolähteet.

notify.email palautti accepted, mutta sähköposti ei tullut perille. SMTP-lähetys on asynkroninen — accepted tarkoittaa, että sähköposti lähti sovelluksen sähköpostikanavaan. Tarkista SMTP-määritys sovelluksen Ilmoitukset-asetuksista ja vastaanottajan roskapostikansio.

Voinko käyttää SDK:ta vahtimisikkunan validoinnissa? Kyllä — validointi ajetaan samassa ympäristössä kuin pääskripti, samalla input-arvolla ja samalla SDK:lla. Katso Ajastukset.