Dokumentumok importálása

Ez az útmutató megmutatja, hogyan juttathatod be a dokumentumaidat a Sursába a kártya-API-val: néhány dokumentumot egy szkriptből, vagy egy rendszer összes dokumentumát egy rendszeresen futó feladattal. Minden dokumentumból kártya lesz egy gyűjteményben. A felhasználók megtalálják a keresésben, az asszisztens válaszol belőle, és mint bármely más kártyának, van felelőse, vannak címkéi, ellenőrzése és jogosultságai.

Olyan API-kulcsra van szükséged, amelynek cards:write hatóköre és a célgyűjteménybe írni képes szerepköre (editor vagy admin) van. A példák a Gyorsindítás segédfüggvényét használják.

A megfelelő végpont kiválasztása

Mindenhez, amit többször importálsz, használd az external_id mezőt. Így minden importálás megismételhető: az újabb futtatás frissíti a korábban létrehozott kártyákat, ahelyett, hogy másolatokat adna hozzá.

Kártya létrehozása vagy cseréje a saját azonosítóddal

A PUT /v1/cards-by-external-id/{external_id} a rekord azonosítóját várja a saját rendszeredből. Ha egyetlen kártyának sincs ilyen external_id értéke, létrehoz egyet (201). Ha van ilyen kártya, lecseréli annak tartalmát és adatait (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"}
  }'

Mi történik ismétléskor:

• A tartalom nem változott: nem készül új verzió. A válasz 200, "status": "skipped" és "reason": "unchanged" értékkel. A kérés megismétlése mindig biztonságos, Idempotency-Key nélkül is.
• A tartalom megváltozott: a kártya új verziót kap, és újraindexelődik. A címe, a címkéi, a felelőse, a kategóriája és a metadata mezője az elküldött értékeket veszi fel; a metadata egészében cserélődik.
• A gyűjtemény és a mappa csak a kártya létrehozásakor érvényesül. Ha később át szeretnéd helyezni a kártyát, módosítsd a PATCH /v1/cards/{card_id} végponttal.

Az új verzió – mint a tartalom bármely módosítása – megszünteti a kártya ellenőrzött állapotát: egy ellenőrzőnek újra meg kell erősítenie.

Szövegformátumok

Várakozás a kártyára vagy anélkül

Alapértelmezés szerint a kérés akkor tér vissza, amikor a kártya már megtalálható, "status": "ready" értékkel és a card mezőben a kártyával. Ez egy rövid szövegnél a másodperc töredéke, egy hosszú fájlnál egy perc vagy több.

Tömeges importálásnál küldd el a "async": true értéket. A válasz azonnal megérkezik "status": "queued" értékkel, a job mezőben pedig az indexelési feladattal (és annak job_id azonosítójával). A feladatot a GET /v1/jobs/{job_id} végponttal ellenőrizheted, vagy az összes feladatot követheted a GET /v1/jobs/stream folyamban. A feladat done, error vagy canceled status értékkel zárul.

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

Fájl feltöltése

A fájlok multipart/form-data kérésben, a file mezőben érkeznek. A Sursa beolvassa a PDF-, Word-, Excel-, PowerPoint-fájlokat, az OpenDocument-munkafüzeteket, a CSV-, Markdown-, HTML- és AsciiDoc-fájlokat, az e-maileket (.eml), az egyszerű szöveget és a gyakori képformátumokat. Ellenőrzi, hogy a fájl neve, megadott típusa és tartalma egyezik-e, és eltérés esetén 415 válasszal elutasítja.

Ha fájlkártyát szeretnél létrehozni vagy lecserélni a saját azonosítóddal, küldd a fájlt ugyanarra a PUT /v1/cards-by-external-id/{external_id} végpontra:

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

Űrlapban a tags vesszővel elválasztott karakterlánc, a metadata pedig karakterláncként írt JSON-objektum. A title nélküli új kártya a fájl nevét kapja címként.

Ha egy fájlt egyszer, saját azonosító nélkül szeretnél hozzáadni, használd a POST /v1/cards végpontot ugyanezzel az űrlappal és egy Idempotency-Key fejléccel. Ha olyan fájlt töltesz fel, amely már megvan a gyűjteményben, a válasz "status": "skipped" lesz "duplicate": true értékkel és a meglévő card_id azonosítóval, hacsak nem adsz meg external_id értéket.

Egy fájl méretét a telepítés korlátozza (alapértelmezés szerint 200 MB). Nagyobb fájloknál vagy megbízhatatlan hálózaton előbb részenként töltsd fel a fájlt.

Egy kártya tartalmának cseréje

Ha már ismered egy kártya Sursában használt azonosítóját, a PUT /v1/cards/{card_id}/content lecseréli a szövegét vagy a fájlját, és minden mást megtart: a felelőst, a címkéket, az ellenőrzőket, az ellenőrzési időközt és a kézzel beállított kategóriát.

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

• Ugyanaz a tartalom ismét "status": "skipped" választ ad "reason": "unchanged" értékkel.
• Az éppen indexelés alatt álló kártyára a válasz 409 a cards.indexing_in_progress kóddal. Néhány másodperc múlva próbáld újra.
• A forrásból, például összekötőből vagy egyéni forrásból származó kártya csak a forrásában módosítható: cards.managed_by_source.
• A kulcsnak a teljes kártyát látnia kell; a csak részben látható kártyára a válasz cards.content_whole_access.

Sok dokumentum importálása

A rekordjaidon PUT /v1/cards-by-external-id/… kérésekkel végigmenő ciklus a legegyszerűbb tömeges importálás, és bármikor biztonságosan leállítható és újraindítható. Hogy gyors legyen, és kímélje a gyakorisági korlátot:

1. Küldd el a "async": true értéket, hogy minden kérés azonnal visszatérjen, amint a kártya bekerült a sorba.
2. Futtass néhány kérést párhuzamosan (4–8), és lassíts, ha a RateLimit fejléc szerint kevés kérés maradt. Lásd: Gyakorisági korlátok és kvóták.
3. 429 esetén várd ki a Retry-After idejét; hálózati hiba vagy 5xx esetén próbáld újra ugyanazt a kérést. Az ismétlések ártalmatlanok.
4. Jegyezd fel minden hibával végződő rekord external_id értékét, és a végén ezeket próbáld újra.

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

Fájlokat tartalmazó ZIP-archívumnál a POST /v1/cards/archive egyetlen kéréssel kártyát készít minden benne lévő támogatott fájlból. Azonnal válaszol a tervvel (mely fájlokból lesz kártya, melyek maradnak ki, és miért) és egy feladattal; az eredményt a GET /v1/archives/{job_id} jelenti.

Importált kártyák keresése és eltávolítása

• Egy kártyát a saját azonosítód alapján a GET /v1/cards-by-external-id/{external_id} végponttal olvashatsz be.
• Egy importálás kártyáit metaadat-szűrővel listázhatod: GET /v1/cards?metadata[source]=helpdesk. Lásd: Metaadatok.
• Egy kártyát a DELETE /v1/cards/{card_id} végponttal törölhetsz.

Gyakori hibák