Dokumentide importimine

See juhend näitab, kuidas kaartide API abil oma dokumendid Sursasse paigutada: mõni dokument skriptist või süsteemi kõik dokumendid regulaarse tööga. Igast dokumendist saab kogus kaart. Inimesed leiavad selle otsinguga, assistent vastab selle põhjal ning sellel on vastutaja, sildid, kontroll ja õigused nagu igal teisel kaardil.

Vajate API-võtit ulatusega cards:write ja rolliga, mis saab sihtkogusse kirjutada (editor või admin). Näited kasutavad abifunktsiooni juhendist Kiirjuhend.

Õige lõpp-punkti valimine

Kõige puhul, mida impordite rohkem kui üks kord, kasutage välja external_id. See muudab iga impordi korratavaks: uus käivitus uuendab varem loodud kaarte, selle asemel et lisada koopiaid.

Kaardi loomine või asendamine teie ID järgi

PUT /v1/cards-by-external-id/{external_id} võtab vastu teie süsteemi kirje ID. Kui ühelgi kaardil ei ole sellist väärtust external_id, loob see kaardi (201). Kui kaardil see on, asendab see kaardi sisu ja üksikasjad (200).

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/kb-article-1042 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": 3,
    "folder_id": "0f8e2d7c-4b6a-4e1f-9c3d-2a5b8e7f1c40",
    "title": "Returning a damaged item",
    "content_type": "html",
    "body": "<h2>Damaged items</h2><p>Send a photo within 7 days and we ship a replacement.</p>",
    "tags": ["returns", "shipping"],
    "metadata": {"source": "helpdesk", "article_id": "1042"}
  }'

Mis juhtub kordamisel:

• Sisu ei muutunud: uut versiooni ei looda. Vastus on 200 väärtustega "status": "skipped" ja "reason": "unchanged". Päringu kordamine on alati turvaline, isegi ilma päiseta Idempotency-Key.
• Sisu muutus: kaart saab uue versiooni ja indekseeritakse uuesti. Selle pealkiri, sildid, vastutaja, kategooria ja metadata saavad teie saadetud väärtused; metadata asendatakse tervikuna.
• Kogu ja kaust rakenduvad ainult kaardi loomisel. Kaardi hilisemaks teisaldamiseks muutke seda päringuga PATCH /v1/cards/{card_id}.

Uus versioon eemaldab kaardi kontrolli nagu iga sisumuudatus: kontrollija kinnitab kaardi uuesti.

Tekstivormingud

Kas oodata kaardi valmimist

Vaikimisi tagastab päring vastuse siis, kui kaart on leidmiseks valmis, väärtusega "status": "ready" ja kaardiga väljal card. Lühikese teksti puhul võtab see sekundi murdosa, pika faili puhul minuti või rohkem.

Hulgiimpordi puhul saatke "async": true. Vastus tuleb kohe väärtusega "status": "queued" ja indekseerimistööga väljal job (koos selle väärtusega job_id). Kontrollige tööd päringuga GET /v1/jobs/{job_id} või jälgige kõiki töid voos GET /v1/jobs/stream. Töö lõpeb, kui selle status on done, error või canceled.

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

Faili üleslaadimine

Failid saadetakse päringus multipart/form-data väljal file. Sursa loeb PDF-, Wordi-, Exceli- ja PowerPointi faile, OpenDocumenti tabeleid, CSV-, Markdowni-, HTML- ja AsciiDoci faile, e-kirju (.eml), lihtteksti ja levinud pildivorminguid. See kontrollib, et faili nimi, deklareeritud tüüp ja sisu ühtiksid, ning lükkab mittevastavuse tagasi vastusega 415.

Failikaardi loomiseks või asendamiseks teie ID järgi saatke fail samale lõpp-punktile PUT /v1/cards-by-external-id/{external_id}:

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/handbook-2026 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -F "file=@employee-handbook.pdf" \
  -F "collection_id=3" \
  -F "tags=hr,policies" \
  -F 'metadata={"owner_team":"people"}'

Vormis on tags komadega eraldatud string ja metadata stringina kirjutatud JSON-objekt. Uus kaart ilma väljata title saab pealkirjaks faili nime.

Faili ühekordseks lisamiseks ilma oma ID-ta kasutage lõpp-punkti POST /v1/cards sama vormi ja päisega Idempotency-Key. Kui laadite üles faili, mis kogus juba on, tagastatakse "status": "skipped" koos väärtusega "duplicate": true ja olemasoleva kaardi card_id, välja arvatud juhul, kui edastate external_id.

Ühe faili suurust piirab paigaldus (vaikimisi 200 MB). Suuremate failide või ebausaldusväärse võrgu korral laadige fail esmalt üles osadena.

Kaardi sisu asendamine

Kui kaardi Sursa ID on teil juba olemas, asendab PUT /v1/cards/{card_id}/content selle teksti või faili ja säilitab kõik muu: vastutaja, sildid, kontrollijad, kontrolli intervalli ja käsitsi määratud kategooria.

curl -X PUT https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60/content \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content_type": "markdown", "body": "# Refund policy\n\nRefunds are processed within 10 days."}'

• Sama sisu uuesti saatmine tagastab "status": "skipped" koos väärtusega "reason": "unchanged".
• Kaart, mida parajasti indekseeritakse, tagastab 409 koodiga cards.indexing_in_progress. Proovige mõne sekundi pärast uuesti.
• Allikast, näiteks konnektorist või kohandatud allikast, pärinevat kaarti muudetakse ainult selle allikas: cards.managed_by_source.
• Võtmel peab olema lubatud näha kogu kaarti; osaliselt nähtav kaart tagastab cards.content_whole_access.

Paljude dokumentide importimine

Tsükkel üle teie kirjete päringuga PUT /v1/cards-by-external-id/… on lihtsaim hulgiimport ning seda on turvaline igal hetkel peatada ja uuesti käivitada. Et see oleks kiire ja arvestaks sageduspiiranguga:

1. Saatke "async": true, et iga päring tagastaks vastuse kohe, kui kaart on järjekorda pandud.
2. Käivitage paar päringut paralleelselt (4–8) ja aeglustage, kui päis RateLimit näitab, et päringuid on vähe alles. Vt Sageduspiirangud ja kvoodid.
3. Vastuse 429 korral oodake päises Retry-After antud aeg ära; võrguvea või vastuse 5xx korral korrake sama päringut. Kordused on ohutud.
4. Märkige üles iga veaga lõppenud kirje external_id ja proovige need lõpus uuesti.

import { api } from "./sursa.mjs";

async function importAll(records, concurrency = 6) {
  const failed = [];
  const queue = [...records];
  async function worker() {
    for (let record = queue.shift(); record; record = queue.shift()) {
      try {
        await api("PUT", `/v1/cards-by-external-id/${encodeURIComponent(record.id)}`, {
          collection_id: 3,
          title: record.title,
          content_type: "html",
          body: record.html,
          metadata: { source: "helpdesk" },
          async: true,
        });
      } catch (error) {
        failed.push({ id: record.id, error: String(error) });
      }
    }
  }
  await Promise.all(Array.from({ length: concurrency }, worker));
  return failed;
}

Failide ZIP-arhiivi puhul muudab POST /v1/cards/archive ühe päringuga iga arhiivis oleva toetatud faili kaardiks. See vastab kohe plaaniga (millistest failidest saavad kaardid, millised jäetakse vahele ja miks) ning tööga; GET /v1/archives/{job_id} annab teada tulemuse.

Imporditud kaartide leidmine ja eemaldamine

• Lugege kaarti oma ID järgi päringuga GET /v1/cards-by-external-id/{external_id}.
• Loetlege ühe impordi kaardid metaandmete filtriga: GET /v1/cards?metadata[source]=helpdesk. Vt Metaandmed.
• Kustutage kaart päringuga DELETE /v1/cards/{card_id}.

Levinud vead