Mine sisu juurde
Sursa Developers

Kiirjuhend

See juhend viib teid viie minutiga nullist töötava integratsioonini: loote API-võtme, kontrollite seda, lisate teadmusbaasi dokumendi, leiate selle üles ja esitate selle kohta küsimuse. Iga samm on üks HTTP-päring. Valige programmeerimiskeel ükskõik millises näites üks kord; kõik lehe näited vahetuvad koos sellega.

Keelevalikuga näited kasutavad selle portaali API-aadressi: Sursa pilves https://api.sursa.com, muidu teie oma paigalduse API-aadressi. Kui näites on https://api.example.com, pange selle asemele oma API-aadress. Kui te ei ole kindel, milline aadress teil on, vt API-aadress ja keskkonnad.

1. Looge API-võti

Organisatsiooni administraator loob võtmed Sursas jaotises Administration → API keys (haldus → API-võtmed). Andke võtmele nimi, mis ütleb, kus seda kasutatakse (näiteks „CRM sync“), valige selle roll ja, kui soovite võtit veelgi kitsendada, selle ulatused. Võti saab teha seda, mida selle rolliga kasutaja, ja mitte rohkem, kui selle ulatused lubavad. Selle juhendi jaoks piisab rollist editor.

Võtit näidatakse üks kord. Hoidke seda oma süsteemi saladuste hoidlas ja edastage see oma koodile keskkonnamuutujas:

export SURSA_API_KEY="kb_…"

Iga päring saadab võtme päises Authorization bearer-loana. Juhend API-võtmed ja ulatused selgitab rolle, ulatusi, aegumist ja uuendamist.

2. Seadistage klient

Teeki ei ole vaja: API on tavaline HTTPS ja JSON. Selle juhendi näited kasutavad igas keeles väikest abifunktsiooni. Kopeerige oma keele abifunktsioon; ka järgmised juhendid kasutavad seda. Ametlikud klienditeegid on loetletud lehel SDK-d.

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

3. Kontrollige võtit

GET /v1/me kirjeldab päringu tegijat: organisatsiooni, võtit, selle rolli ja ulatusi ning sellele kehtivat sageduspiirangut. See töötab iga kehtiva võtmega, seega on see iga integratsiooni parim esimene päring.

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}
}

Vastus 401 koodiga auth.not_authenticated tähendab, et võti puudub, on tühistatud või valesti sisestatud; api_keys.expired tähendab, et selle kehtivus on lõppenud.

4. Leidke kogu

Kaardid asuvad kogudes. GET /v1/collections loetleb kogud, mida teie võti näeb:

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

Märkige üles selle kogu id ja name, millega soovite töötada. Allolevad näited kasutavad kogu 3, mille nimi on support.

5. Lisage dokument

PUT /v1/cards-by-external-id/{external_id} loob kaardi teie enda ID-ga või asendab selle, kui kaart on juba olemas. Päringu kahekordne käivitamine on turvaline: teisel korral ei ole sisu muutunud ja vastus on skipped põhjusega unchanged. Kasutage väärtusena external_id oma süsteemi kirje ID-d.

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."
  }'

Päring tagastab vastuse siis, kui kaart on leidmiseks valmis: uue kaardi puhul 201 väärtusega "status": "ready", asendatud kaardi puhul 200. HTML ja lihttekst toimivad samamoodi väärtusega "content_type": "html" või "text". Failid (PDF, Word, Excel ja teised) saadetakse sama lõpp-punkti kaudu vormingus multipart/form-data; juhend Dokumentide importimine käsitleb faile, kaustu, metaandmeid ja paljude dokumentide importi.

POST /v1/search leiab kaartidest päringule vastavad tekstilõigud, parima tabamuse esimesena:

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 võtab vastu kogu nime. Ilma selleta otsitakse kogust, mille nimi on default.

7. Esitage küsimus

POST /v1/ask vastab tavakeeles esitatud küsimusele ja tagastab vastuse allikad. Assistent leiab vajalikud teadmised ja vastab ainult nende kaartide põhjal, mida võtmel on lubatud lugeda.

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"}'

Kui midagi asjakohast ei leita, on vastus ikkagi 200, väärtusega "empty": "no_hits" ja lühikese selgitusega väljal answer. Teie kood otsustab, mida kasutajale sel juhul näidata.

Järgmised sammud