Importujte dokumenty

Tento návod ukazuje, ako dostať vaše dokumenty do Sursy cez API kariet: niekoľko dokumentov zo skriptu alebo všetky dokumenty systému pravidelnou úlohou. Každý dokument sa stane kartou v kolekcii. Ľudia ju nájdu vo vyhľadávaní, asistent z nej odpovedá a má vlastníka, štítky, overenie a oprávnenia ako ktorákoľvek iná karta.

Potrebujete kľúč API s rozsahom cards:write a rolou, ktorá smie zapisovať do cieľovej kolekcie (editor alebo admin). Ukážky používajú pomocnú funkciu z Rýchleho štartu.

Vyberte správnu operáciu

Pri všetkom, čo importujete viac ako raz, používajte external_id. Vďaka nemu je každý import opakovateľný: opätovné spustenie aktualizuje karty, ktoré vytvoril, namiesto toho, aby pridalo kópie.

Vytvorenie alebo nahradenie karty podľa vášho identifikátora

PUT /v1/cards-by-external-id/{external_id} prijíma identifikátor záznamu vo vašom systéme. Ak žiadna karta toto external_id nemá, vytvorí novú (201). Ak ho niektorá karta má, nahradí jej obsah a údaje (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"}
  }'

Čo sa stane pri opakovaní:

• Obsah sa nezmenil: nová verzia nevznikne. Odpoveď je 200 s "status": "skipped" a "reason": "unchanged". Opakovať požiadavku je vždy bezpečné, aj bez Idempotency-Key.
• Obsah sa zmenil: karta dostane novú verziu a znova sa indexuje. Jej názov, štítky, vlastník, kategória a metadata prevezmú odoslané hodnoty; metadata sa nahradí ako celok.
• Kolekcia a priečinok platia len pri vytvorení karty. Ak chcete kartu neskôr presunúť, zmeňte ju cez PATCH /v1/cards/{card_id}.

Nová verzia odstráni overenie karty, ako každá zmena obsahu: overovateľ ju musí znova overiť.

Textové formáty

Čakať na kartu, alebo nie

Predvolene sa požiadavka vráti, keď je karta pripravená na vyhľadanie, s "status": "ready" a kartou v card. Trvá to od zlomku sekundy pri krátkom texte po minútu alebo viac pri dlhom súbore.

Pri hromadných importoch odošlite "async": true. Odpoveď príde hneď s "status": "queued" a úlohou indexovania v job (s jej job_id). Úlohu skontrolujte cez GET /v1/jobs/{job_id} alebo sledujte všetky úlohy v GET /v1/jobs/stream. Úloha skončí so status done, error alebo canceled.

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

Nahratie súboru

Súbory sa posielajú v požiadavke multipart/form-data v poli file. Sursa číta PDF, Word, Excel, PowerPoint, tabuľky OpenDocument, CSV, Markdown, HTML, AsciiDoc, e-maily (.eml), obyčajný text a bežné formáty obrázkov. Overí, že názov súboru, deklarovaný typ a obsah sa zhodujú, a nezhodu odmietne s 415.

Ak chcete vytvoriť alebo nahradiť kartu so súborom podľa vlastného identifikátora, odošlite súbor na tú istú operáciu 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"}'

Vo formulári je tags reťazec oddelený čiarkami a metadata objekt JSON zapísaný ako reťazec. Nová karta bez title dostane ako názov názov súboru.

Ak chcete súbor pridať raz, bez vlastného identifikátora, použite POST /v1/cards s tým istým formulárom a s Idempotency-Key. Nahratie súboru, ktorý už kolekcia má, vráti "status": "skipped" s "duplicate": true a existujúcim card_id, pokiaľ neodošlete external_id.

Veľkosť jedného súboru obmedzuje inštalácia (predvolene 200 MB). Väčšie súbory alebo súbory v nespoľahlivých sieťach najprv nahrajte po častiach.

Nahradenie obsahu karty

Keď už ID karty v Surse máte, PUT /v1/cards/{card_id}/content nahradí jej text alebo súbor a všetko ostatné zachová: vlastníka, štítky, overovateľov, interval overovania a ručne nastavenú kategóriu.

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

• Rovnaký obsah znova vráti "status": "skipped" s "reason": "unchanged".
• Karta, ktorá sa práve indexuje, vráti 409 s kódom cards.indexing_in_progress. Zopakujte o niekoľko sekúnd.
• Karta, ktorá pochádza zo zdroja, napríklad z konektora alebo vlastného zdroja, sa mení len vo svojom zdroji: cards.managed_by_source.
• Kľúč musí vidieť celú kartu; čiastočne viditeľná karta vráti cards.content_whole_access.

Import mnohých dokumentov

Slučka cez vaše záznamy s PUT /v1/cards-by-external-id/… je najjednoduchší hromadný import a možno ju bezpečne kedykoľvek zastaviť a spustiť znova. Aby bola rýchla a ohľaduplná k limitu frekvencie:

1. Odošlite "async": true, aby sa každá požiadavka vrátila hneď, ako sa karta zaradí do frontu.
2. Spúšťajte niekoľko požiadaviek súbežne (4 až 8) a spomaľte, keď hlavička RateLimit ukazuje, že zostáva málo požiadaviek. Pozri Limity frekvencie a kvóty.
3. Pri 429 počkajte podľa Retry-After; pri sieťovej chybe alebo 5xx zopakujte tú istú požiadavku. Opakovania neuškodia.
4. Zaznamenajte external_id každého záznamu, ktorý skončí chybou, a tieto záznamy zopakujte na konci.

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

Pri archíve ZIP so súbormi POST /v1/cards/archive jednou požiadavkou premení každý podporovaný súbor v ňom na kartu. Hneď odpovie plánom (ktoré súbory sa stanú kartami, ktoré sa preskočia a prečo) a úlohou; výsledok oznámi GET /v1/archives/{job_id}.

Vyhľadanie a odstránenie importovaných kariet

• Kartu podľa vlastného identifikátora načítate cez GET /v1/cards-by-external-id/{external_id}.
• Karty jedného importu vypíšete filtrom metadát: GET /v1/cards?metadata[source]=helpdesk. Pozri Metadáta.
• Kartu vymažete cez DELETE /v1/cards/{card_id}.

Bežné chyby