Dokumentų importas

Ši instrukcija parodo, kaip kortelių API perkelti jūsų dokumentus į Sursą: kelis dokumentus iš scenarijaus arba visus sistemos dokumentus reguliariu darbu. Kiekvienas dokumentas tampa kortele rinkinyje. Žmonės ją randa paieškoje, asistentas pagal ją atsako, ir ji, kaip ir bet kuri kita kortelė, turi atsakingą asmenį, žymas, tikrinimą ir leidimus.

Jums reikia API rakto su apimtimi cards:write ir vaidmens, kuris gali rašyti į tikslinį rinkinį (editor arba admin). Pavyzdžiuose naudojama pagalbinė funkcija iš Greitosios pradžios.

Tinkamos operacijos pasirinkimas

Viskam, ką importuojate daugiau nei kartą, naudokite external_id. Tada kiekvieną importą galima pakartoti: paleistas dar kartą, jis atnaujina savo sukurtas korteles, o ne prideda kopijų.

Kortelės kūrimas arba pakeitimas pagal jūsų ID

PUT /v1/cards-by-external-id/{external_id} priima įrašo ID jūsų sistemoje. Jei jokia kortelė neturi šio external_id, ji sukuria kortelę (201). Jei kortelė jį turi, ji pakeičia kortelės turinį ir duomenis (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"}
  }'

Kas vyksta pakartojus:

• Turinys nepasikeitė: nauja versija nekuriama. Atsakas – 200 su "status": "skipped" ir "reason": "unchanged". Užklausą kartoti visada saugu, net be Idempotency-Key.
• Turinys pasikeitė: kortelė gauna naują versiją ir indeksuojama iš naujo. Jos pavadinimas, žymos, atsakingas asmuo, kategorija ir metadata gauna jūsų išsiųstas reikšmes; metadata pakeičiami visi iš karto.
• Rinkinys ir aplankas taikomi tik kuriant kortelę. Kad kortelę perkeltumėte vėliau, pakeiskite ją operacija PATCH /v1/cards/{card_id}.

Nauja versija, kaip ir bet koks turinio pakeitimas, panaikina kortelės patikrinimą: tikrintojas ją patvirtina iš naujo.

Teksto formatai

Laukti kortelės ar ne

Pagal numatytuosius nustatymus užklausa grąžina atsaką, kai kortelę jau galima rasti, su "status": "ready" ir kortele lauke card. Tai trunka nuo sekundės dalies trumpam tekstui iki minutės ar ilgiau ilgam failui.

Masiniam importui siųskite "async": true. Atsakas ateina iš karto su "status": "queued" ir indeksavimo darbu lauke job (su jo job_id). Darbą tikrinkite operacija GET /v1/jobs/{job_id} arba visus darbus stebėkite per GET /v1/jobs/stream. Darbas baigiasi su status done, error arba canceled.

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

Failo įkėlimas

Failai siunčiami multipart/form-data užklausa, lauke file. Sursa skaito PDF, Word, Excel, PowerPoint, OpenDocument skaičiuokles, CSV, Markdown, HTML, AsciiDoc, el. laiškus (.eml), paprastą tekstą ir įprastus paveikslėlių formatus. Ji patikrina, ar failo pavadinimas, nurodytas tipas ir turinys sutampa, o neatitikimą atmeta su 415.

Kad sukurtumėte ar pakeistumėte failo kortelę pagal savo ID, siųskite failą į tą pačią 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"}'

Formoje tags yra kableliais atskirta eilutė, o metadata – eilute užrašytas JSON objektas. Nauja kortelė be title pavadinimu gauna failo vardą.

Kad failą pridėtumėte vieną kartą, be savo ID, naudokite POST /v1/cards su ta pačia forma ir Idempotency-Key. Įkėlus failą, kurį rinkinys jau turi, grąžinama "status": "skipped" su "duplicate": true ir esamu card_id, nebent perduodate external_id.

Vieno failo dydį riboja diegimas (numatytoji reikšmė – 200 MB). Didesnius failus, taip pat esant nepatikimam tinklui, pirmiausia įkelkite dalimis.

Kortelės turinio pakeitimas

Kai jau turite kortelės Sursos ID, PUT /v1/cards/{card_id}/content pakeičia jos tekstą ar failą ir išsaugo visa kita: atsakingą asmenį, žymas, tikrintojus, tikrinimo intervalą ir ranka nustatytą kategoriją.

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

• Tas pats turinys dar kartą grąžina "status": "skipped" su "reason": "unchanged".
• Kortelė, kuri šiuo metu indeksuojama, grąžina 409 su kodu cards.indexing_in_progress. Pakartokite po kelių sekundžių.
• Kortelė, kilusi iš šaltinio, pavyzdžiui, jungties ar pasirinktinio šaltinio, keičiama tik savo šaltinyje: cards.managed_by_source.
• Raktui turi būti leidžiama matyti visą kortelę; iš dalies matoma kortelė grąžina cards.content_whole_access.

Daugelio dokumentų importas

Ciklas per jūsų įrašus su PUT /v1/cards-by-external-id/… – paprasčiausias masinis importas, kurį bet kurioje vietoje saugu sustabdyti ir paleisti iš naujo. Kad jis būtų greitas ir neviršytų užklausų dažnio limito:

1. Siųskite "async": true, kad kiekviena užklausa grąžintų atsaką, kai tik kortelė įtraukiama į eilę.
2. Vykdykite kelias užklausas lygiagrečiai (nuo 4 iki 8) ir sulėtinkite tempą, kai antraštė RateLimit rodo, kad užklausų liko nedaug. Žr. Užklausų dažnio limitai ir kvotos.
3. Gavus 429, palaukite Retry-After; esant tinklo klaidai ar 5xx, pakartokite tą pačią užklausą. Pakartojimai nekenksmingi.
4. Užsirašykite kiekvieno klaida pasibaigusio įrašo external_id ir pabaigoje pakartokite juos.

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

Failų ZIP archyvui POST /v1/cards/archive viena užklausa kiekvieną viduje esantį palaikomą failą paverčia kortele. Ji iš karto grąžina planą (kurie failai taps kortelėmis, kurie bus praleisti ir kodėl) ir darbą; GET /v1/archives/{job_id} praneša rezultatą.

Importuotų kortelių paieška ir šalinimas

• Kortelę pagal savo ID nuskaitykite operacija GET /v1/cards-by-external-id/{external_id}.
• Vieno importo korteles išvardykite su metaduomenų filtru: GET /v1/cards?metadata[source]=helpdesk. Žr. Metaduomenys.
• Kortelę ištrinkite operacija DELETE /v1/cards/{card_id}.

Dažnos klaidos