KEPLIN Docs

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.

Kehote LLM:lle — koko SDK:n sopimus tekstinä, valmiina liitettäväksi tekoälyavustajaan.
Kehote LLM:lle — koko SDK:n sopimus tekstinä, valmiina liitettäväksi tekoälyavustajaan.

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.

Yhden suorituksen tiedot — palautettu tulos ja skriptin kirjoittamat lokirivit.
Yhden suorituksen tiedot — palautettu tulos ja skriptin kirjoittamat lokirivit.

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.

Sovelluksen Salaisuudet-sivu — avaimet, jotka skriptit lukevat funktiolla secrets.get.
Sovelluksen Salaisuudet-sivu — avaimet, jotka skriptit lukevat funktiolla secrets.get.

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.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ä.

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.update muuttaa vain annetut kentät, ja email=None poistaa sähköpostiosoitteen. users.list ottaa poistetut tilit mukaan, kun include_disabled=True.
  • Muutokset ovat voimassa heti: poistettu tili menettää pääsyn seuraavassa pyynnössä, ja set_password pää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.