Pereiti prie turinio
Sursa Developers

Greitoji pradžia

Ši instrukcija per penkias minutes nuves jus nuo nulio iki veikiančios integracijos: sukursite API raktą, jį patikrinsite, pridėsite dokumentą į žinių bazę, jį surasite ir užduosite apie jį klausimą. Kiekvienas žingsnis – viena HTTP užklausa. Kalbą pasirinkite vieną kartą bet kuriame pavyzdyje – kartu persijungs visi puslapio pavyzdžiai.

Pavyzdžiuose su kalbos perjungikliu naudojamas šio portalo API adresas: Sursos debesyje – https://api.sursa.com, o jūsų diegime – jo API adresas. Kur pavyzdyje rodomas https://api.example.com, jo vietoje įrašykite savo API adresą. Jei nežinote, kurį adresą turite, žr. API adresas ir aplinkos.

1. Sukurkite API raktą

Organizacijos administratorius kuria raktus Sursoje, skiltyje Administration → API keys (administravimas, API raktai). Suteikite raktui pavadinimą, iš kurio aišku, kur jis naudojamas (pavyzdžiui, „CRM sync“), pasirinkite jo vaidmenį ir, jei norite dar labiau apriboti, apimtis. Raktas gali daryti tai, ką gali to vaidmens naudotojas, bet ne daugiau, nei leidžia jo apimtys. Šiai instrukcijai pakanka vaidmens editor.

Raktas parodomas vieną kartą. Laikykite jį savo sistemos slaptųjų duomenų saugykloje ir perduokite kodui aplinkos kintamuoju:

export SURSA_API_KEY="kb_…"

Kiekviena užklausa siunčia raktą antraštėje Authorization kaip Bearer žetoną. API raktai ir apimtys paaiškina vaidmenis, apimtis, galiojimo pabaigą ir rotaciją.

2. Paruoškite klientą

Jokios bibliotekos nereikia: API – tai paprastas HTTPS ir JSON. Šios instrukcijos pavyzdžiuose kiekviena kalba naudoja nedidelę pagalbinę funkciją. Nukopijuokite savo kalbos funkciją – tolesnės instrukcijos naudoja tą pačią. Oficialios klientų bibliotekos išvardytos skyriuje SDK.

# cURL needs no setup: each example below is a complete command.
export SURSA_API="https://api.sursa.com"

3. Patikrinkite raktą

GET /v1/me aprašo užklausos siuntėją: organizaciją, raktą, jo vaidmenį ir apimtis bei jam taikomą užklausų dažnio limitą. Ji veikia su bet kuriuo galiojančiu raktu, todėl tai geriausia pirmoji kiekvienos integracijos užklausa.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"
{
  "principal": "api_key",
  "org": {"id": 1, "slug": "acme", "name": "Acme"},
  "key": {"id": 42, "name": "CRM sync", "prefix": "kb_3f9c", "role": "editor"},
  "user": null,
  "role": "editor",
  "scopes": ["cards:read", "cards:write", "search", "ask"],
  "data_profile": null,
  "expires_at": null,
  "rate_limit": {"class": "standard", "requests_per_second": 20, "burst": 100}
}

Atsakas 401 su kodu auth.not_authenticated reiškia, kad rakto nėra, jis atšauktas arba įvestas su klaida; api_keys.expired reiškia, kad jo galiojimas baigėsi.

4. Raskite rinkinį

Kortelės saugomos rinkiniuose. GET /v1/collections pateikia rinkinių, kuriuos mato jūsų raktas, sąrašą:

curl https://api.sursa.com/v1/collections \
  -H "Authorization: Bearer $SURSA_API_KEY"

Užsirašykite rinkinio, su kuriuo norite dirbti, id ir name. Toliau pavyzdžiuose naudojamas rinkinys 3, pavadintas support.

5. Pridėkite dokumentą

PUT /v1/cards-by-external-id/{external_id} sukuria kortelę su jūsų pačių ID arba ją pakeičia, jei tokia kortelė jau yra. Užklausą saugu vykdyti du kartus: antrą kartą turinys nepasikeitęs, o atsakas – skipped su priežastimi unchanged. Kaip external_id naudokite įrašo ID savo sistemoje.

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": 3,
    "title": "Refund policy",
    "content_type": "markdown",
    "body": "# Refund policy\n\nRefunds are processed within 14 days of the request."
  }'

Užklausa grąžina atsaką, kai kortelę jau galima rasti: naujai kortelei – 201 su "status": "ready", pakeistai – 200. HTML ir paprastas tekstas veikia taip pat, su "content_type": "html" arba "text". Failai (PDF, Word, Excel ir kiti) siunčiami ta pačia operacija kaip multipart/form-data; Dokumentų importas aprašo failus, aplankus, metaduomenis ir daugelio dokumentų importą.

POST /v1/search randa kortelių ištraukas, atitinkančias užklausą, – geriausias atitikmuo pirmas:

curl -X POST https://api.sursa.com/v1/search \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund policy", "collection": "support"}'

collection nurodo rinkinio pavadinimą. Be jo ieškoma rinkinyje, pavadintame default.

7. Užduokite klausimą

POST /v1/ask atsako į paprasta kalba užduotą klausimą ir grąžina atsakymo šaltinius. Asistentas randa reikiamas žinias ir atsako tik pagal korteles, kurias raktui leidžiama skaityti.

curl -X POST https://api.sursa.com/v1/ask \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How long does a refund take?", "collection": "support"}'

Kai nieko tinkamo nerandama, atsakas vis tiek yra 200, su "empty": "no_hits" ir trumpu paaiškinimu lauke answer. Ką tokiu atveju parodyti naudotojui, sprendžia jūsų kodas.

Tolesni žingsniai