Skriptien SDK
api_manager-SDK:n kymmenen moduulia — tietolähteet, HTTP, lokit, upload-tiedostot, salaisuudet, ilmoitukset, työnkulut, tilit, raportit ja tekoäly — Python-esimerkkeineen.
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, users, reports, ai
Nämä kymmenen 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. |
users |
Sovelluksen tilien luonti ja muuttaminen sekä roolien antaminen niille. |
reports |
Sovelluksen raporttien luonti PDF- tai Excel-muodossa. |
ai |
Sovelluksen tekoälymallien käyttö: teksti, JSON, työkalut, upotukset, kuvat, ääni ja eräajot. |
Editori täydentää tämän kaiken automaattisesti — nimet, parametrit ja kunkin funktion dokumentaatio ilmestyvät kirjoittaessasi.
Vinkki
Editorin palkin painike Kehote LLM:lle avaa SDK:n täydellisen oppaan, kopioitavaksi painikkeella Kopioi kaikki. Liitä se Claudeen, ChatGPT:hen tai muuhun avustajaan yhdessä sen kanssa, mitä haluat skriptin tekevän — avustaja tuntee siitä lähtien tarkan sopimuksen eikä keksi funktioita, joita ei ole olemassa.

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).
Varoitus
Päivämäärät Oraclessa: vältä niiden välittämistä parametrina — JSON-kuljetus
tekee tyypistä moniselitteisen. Suosi literaalia SQL:ssä:
TO_DATE('2026-06-25','YYYY-MM-DD').
Binäärisarake (bytea, blob, varbinary) saapuu bytes-arvona, ja
bytes-parametri tallennetaan binäärinä:
foto = crm.query_one("select foto from contas where id = ?", [42])["foto"]
crm.query("update contas set foto = ? where id = ?", [novos_bytes, 42])
Yhteys ja transaktiot
Kaikki saman suorituksen kyselyt samaan tietolähteeseen kulkevat saman yhteyden kautta, joka kuuluu vain tälle suoritukselle. Siksi voit käyttää transaktioita:
crm.query("begin")
crm.query("update contas set saldo = saldo - ? where id = ?", [100, 1])
crm.query("update contas set saldo = saldo + ? where id = ?", [100, 2])
crm.query("commit")
Se, mitä ei ole vahvistettu suorituksen päättyessä (virheeseen,
aikarajaan tai peruutettuna), perutaan. Epäonnistunut kysely sulkee
yhteyden, ja seuraava kysely avaa uuden, jo transaktion ulkopuolella. SQL
Serverissä transaktio alkaa komennolla begin transaction. Oraclessa ei
ole begin-komentoa: muutokset tallentuvat vasta commit-komennolla.
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.

Varoitus
Älä tee log(token). Lokit jäävät suoritushistoriaan — lokiin kirjoitettu
salaisuus lakkasi olemasta salaisuus.
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.startpalaa heti kun moottori saapuu ensimmäiseen odotukseen — se ei koskaan jää odottamaan prosessin päättymistä.workflow.signalilmankey-arvoa herättää kaikki kyseisessä tapahtumassa pysähtyneet prosessit;{"woken": 0}ei ole virhe — ketään ei ehkä ollut odottamassa.workflow.complete-kutsussaas_useron 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ä.
users — sovelluksen tilit
Skripti luo ja muuttaa sovelluksen tilejä ja antaa niille rooleja, jotka
ovat jo olemassa. Roolit ja oikeudet luodaan rakennustyökalussa; moduuli ei
luo eikä muuta niitä. user on tilin id (numero) tai käyttäjätunnus
(teksti):
from api_manager import users
users.roles() # ["gestor", "vendedor"]
u = users.create("ana", password=input["args"]["password"],
email="ana@empresa.pt", name="Ana Silva", roles=["vendedor"])
# u = {"id", "username", "email", "name", "disabled", "roles",
# "createdAt", "lastLoginAt"}
users.get("ana") # tili tai None
users.list(role="vendedor") # ilman poistettuja tilejä
users.update("ana", name="Ana M. Silva", disabled=True)
users.set_password("ana", nova)
users.set_roles("ana", ["vendedor", "gestor"])
users.add_role("ana", "gestor")
users.remove_role("ana", "vendedor")
Säännöt, joilla on väliä:
- Säännöt ovat samat kuin rakennustyökalussa ja julkisessa rekisteröinnissä:
käyttäjätunnuksessa 3–120 merkkiä (kirjaimia, numeroita, piste, väliviiva,
_ja@), kelvollinen sähköpostiosoite, salasanassa 8–200 merkkiä, ja vapaa käyttäjätunnus ja sähköpostiosoite, myös toisiinsa nähden. - Tilit tulevat skriptille ilman salasanaa. Ilman
password-arvoa tili pääsee sisään vasta, kun sille on asetettu salasana. users.updatemuuttaa vain annetut kentät, jaemail=Nonepoistaa sähköpostiosoitteen.users.listottaa poistetut tilit mukaan, kuninclude_disabled=True.- Muutokset ovat voimassa heti: poistettu tili menettää pääsyn seuraavassa
pyynnössä, ja
set_passwordpäättää tilin avoimet istunnot. - Jokainen muutos kirjataan auditointiin, mukana se, joka käynnisti skriptin, ja skriptin nimi.
- Anna salasanan argumentille nimi
password: historia Suoritukset piilottaa sen nimiset argumentit.
Virhe nostaa users.Error-poikkeuksen, jolla on pysyvä code: invalid_username, invalid_email, invalid_name, weak_password, username_taken, email_taken, unknown_role, not_found tai
invalid_request.
def main(input):
a = input["args"]
try:
u = users.create(a["username"], password=a["password"], roles=["vendedor"])
except users.Error as e:
if e.code == "username_taken":
return {"ok": False, "virhe": "Käyttäjätunnus on jo käytössä."}
raise
return {"ok": True, "id": u["id"]}
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.
Skripti ajetaan ilman kirjautunutta käyttäjää: reports.render ja
workflow-verbit lukevat ja kirjoittavat tietoja sovelluksena itsenään,
kaikilla aktiivisilla API-rajapinnoilla, niin ajastuksessa kuin
Suorita nyt -toiminnossa.
ai — sovelluksen tekoälymallit
Skriptit kysyvät tekoälymalleilta, jotka sovellus on määrittänyt kohdassa Tekoälymallit, aliaksen nimellä. Palveluntarjoajien avaimet pysyvät palvelimella, eikä skripti näe niitä koskaan:
from api_manager import ai
def main(input):
resumo = ai.chat("Resume este pedido numa frase: " + input["args"]["pedido"])
dados = ai.json(
"Extrai o nome e o email do cliente: " + input["args"]["pedido"],
schema={
"type": "object",
"properties": {"nome": {"type": "string"}, "email": {"type": "string"}},
"required": ["nome", "email"],
},
)
vector = ai.embed(resumo["text"])
return {"resumo": resumo["text"], "cliente": dados, "dimensoes": len(vector)}
| Funktio | Palauttaa |
|---|---|
ai.chat(prompt, ...) |
Dictin, jossa on text, stop_reason, usage, model, provider ja alias. |
ai.json(prompt, schema=..., ...) |
Vastauksen JSONin valmiiksi skeemaa vasten validoituna. |
ai.embed(tekstit) |
Yhden vektorin tekstiä kohden (lista lukuja). |
ai.models() |
Sovelluksen aliakset, kunkin käyttö ja malli. |
ai.run(prompt, tools=[...], ...) |
Lopullisen vastauksen tehtävään, jossa malli käyttää skriptin funktioita, vaiheineen. |
ai.image(prompt, ...) |
Luodut kuvat valmiiksi sovellukseen tallennettuina. |
ai.transcribe(tiedosto, ...) |
Tallenteen tekstin. |
ai.speak(teksti, ...) |
Puheen äänen valmiiksi sovellukseen tallennettuna. |
ai.batch.submit(pyynnot, ...) |
Taustalla käsiteltävän eräajon tunnisteen; ai.batch.get, ai.batch.results ja ai.batch.cancel seuraavat sitä. |
Parametrit, tiedostot, virhekoodit ja rajat ovat sivulla Tekoälyn käyttö skripteissä, Työkalut ja eräajot ja Kuvat ja ääni.
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.