Asiakirjojen tuonti

Tässä oppaassa näytetään, miten viet asiakirjasi Sursaan korttien API:n avulla: muutaman asiakirjan skriptistä tai järjestelmän kaikki asiakirjat säännöllisesti ajettavalla työllä. Jokaisesta asiakirjasta tulee kokoelmaan kortti. Ihmiset löytävät sen haulla, avustaja vastaa sen perusteella, ja sillä on omistaja, tunnisteet, vahvistus ja käyttöoikeudet kuten millä tahansa muulla kortilla.

Tarvitset API-avaimen, jolla on käyttöalue cards:write ja rooli, joka voi kirjoittaa kohdekokoelmaan (editor tai admin). Esimerkit käyttävät apufunktiota, joka esitellään oppaassa Pika-aloitus.

Oikean päätepisteen valinta

Käytä external_id-kenttää kaikessa, mitä tuot useammin kuin kerran. Sen ansiosta jokainen tuonti on toistettavissa: uusi ajo päivittää aiemmin luomansa kortit eikä lisää kopioita.

Kortin luominen tai korvaaminen omalla tunnuksella

PUT /v1/cards-by-external-id/{external_id} ottaa järjestelmäsi tietueen tunnuksen. Jos millään kortilla ei ole tätä external_id-tunnusta, pyyntö luo kortin (201). Jos jollakin kortilla on se, pyyntö korvaa kortin sisällön ja tiedot (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"}
  }'

Mitä toistossa tapahtuu:

• Sisältö ei muuttunut: uutta versiota ei luoda. Vastaus on 200, ja siinä on "status": "skipped" ja "reason": "unchanged". Pyynnön toistaminen on aina turvallista, myös ilman Idempotency-Key-otsaketta.
• Sisältö muuttui: kortti saa uuden version, ja se indeksoidaan uudelleen. Sen otsikko, tunnisteet, omistaja, luokka ja metadata saavat lähettämäsi arvot; metadata korvataan kokonaisuutena.
• Kokoelma ja kansio otetaan huomioon vain kortin luonnissa. Jos haluat siirtää korttia myöhemmin, muuta sitä PATCH /v1/cards/{card_id} -pyynnöllä.

Uusi versio poistaa kortin vahvistuksen, kuten mikä tahansa sisällön muutos: vahvistaja vahvistaa kortin uudelleen.

Tekstimuodot

Odotetaanko korttia vai ei

Oletuksena pyyntö palaa, kun kortti on valmis löydettäväksi, ja vastauksessa on "status": "ready" ja kortti card-kentässä. Tämä kestää sekunnin murto-osasta lyhyellä tekstillä minuuttiin tai pidempään pitkällä tiedostolla.

Massatuonneissa lähetä "async": true. Vastaus tulee heti, ja siinä on "status": "queued" ja indeksointityö job-kentässä (job_id-tunnuksineen). Tarkista työ GET /v1/jobs/{job_id} -pyynnöllä tai seuraa kaikkia töitä virrasta GET /v1/jobs/stream. Työ päättyy, kun status on done, error tai canceled.

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

Tiedoston lataaminen

Tiedostot lähetetään multipart/form-data-pyynnössä file-kentässä. Sursa lukee PDF-, Word-, Excel- ja PowerPoint-tiedostot, OpenDocument-laskentataulukot, CSV-, Markdown-, HTML- ja AsciiDoc-tiedostot, sähköpostit (.eml), pelkän tekstin ja yleiset kuvamuodot. Se tarkistaa, että tiedoston nimi, ilmoitettu tyyppi ja sisältö vastaavat toisiaan, ja hylkää ristiriitaisen tiedoston 415-vastauksella.

Jos haluat luoda tai korvata tiedostokortin omalla tunnuksellasi, lähetä tiedosto samaan PUT /v1/cards-by-external-id/{external_id} -päätepisteeseen:

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

Lomakkeessa tags on pilkuilla eroteltu merkkijono ja metadata merkkijonoksi kirjoitettu JSON-objekti. Uusi kortti ilman title-kenttää saa otsikokseen tiedoston nimen.

Jos haluat lisätä tiedoston kerran ilman omaa tunnusta, käytä POST /v1/cards -pyyntöä samalla lomakkeella ja Idempotency-Key-otsakkeella. Jos lataat tiedoston, joka kokoelmassa jo on, vastaus on "status": "skipped", ja siinä on "duplicate": true ja olemassa oleva card_id, ellet anna external_id-tunnusta.

Yhden tiedoston kokoa rajoittaa asennus (oletuksena 200 Mt). Suuremmat tiedostot, samoin kuin tiedostot epäluotettavissa verkoissa, kannattaa ladata ensin osissa.

Kortin sisällön korvaaminen

Kun tiedät kortin Sursa-tunnuksen, PUT /v1/cards/{card_id}/content korvaa sen tekstin tai tiedoston ja säilyttää kaiken muun: omistajan, tunnisteet, vahvistajat, vahvistusvälin ja käsin asetetun luokan.

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 sisältö uudelleen palauttaa "status": "skipped" ja "reason": "unchanged".
• Kortti, jota indeksoidaan juuri nyt, palauttaa 409-vastauksen ja koodin cards.indexing_in_progress. Yritä uudelleen muutaman sekunnin kuluttua.
• Lähteestä, kuten liittimestä tai mukautetusta lähteestä, peräisin olevaa korttia muutetaan vain sen lähteessä: cards.managed_by_source.
• Avaimen täytyy saada nähdä koko kortti; osittain näkyvä kortti palauttaa koodin cards.content_whole_access.

Monen asiakirjan tuonti

Silmukka, joka käy tietueesi läpi PUT /v1/cards-by-external-id/… -pyynnöillä, on yksinkertaisin massatuonti, ja sen voi turvallisesti pysäyttää ja ajaa uudelleen missä vaiheessa tahansa. Näin teet siitä nopean ja nopeusrajoituksen kannalta ystävällisen:

1. Lähetä "async": true, jotta jokainen pyyntö palaa heti, kun kortti on jonossa.
2. Aja muutama pyyntö rinnakkain (4–8) ja hidasta, kun RateLimit-otsake näyttää, että pyyntöjä on jäljellä vähän. Ks. Nopeusrajoitukset ja kiintiöt.
3. Kun vastaus on 429, odota Retry-After-ajan verran; verkkovirheen tai 5xx-vastauksen jälkeen yritä samaa pyyntöä uudelleen. Toistot ovat vaarattomia.
4. Kirjaa jokaisen virheeseen päättyneen tietueen external_id ja yritä niitä uudelleen lopuksi.

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

ZIP-arkiston tiedostoista POST /v1/cards/archive tekee yhdellä pyynnöllä kortin jokaisesta tuetusta tiedostosta. Se vastaa heti suunnitelmalla (mistä tiedostoista tulee kortteja ja mitkä ohitetaan ja miksi) ja työllä; GET /v1/archives/{job_id} kertoo tuloksen.

Tuotujen korttien etsiminen ja poistaminen

• Lue kortti omalla tunnuksellasi GET /v1/cards-by-external-id/{external_id} -pyynnöllä.
• Listaa yhden tuonnin kortit metatietosuodattimella: GET /v1/cards?metadata[source]=helpdesk. Ks. Metatiedot.
• Poista kortti DELETE /v1/cards/{card_id} -pyynnöllä.

Yleiset virheet