Dokumentu imports

Šajā ceļvedī parādīts, kā ievietot savus dokumentus Sursā ar kartīšu API: dažus dokumentus no skripta vai visus sistēmas dokumentus ar regulāru darbu. Katrs dokuments kļūst par kartīti kolekcijā. Cilvēki to atrod meklēšanā, asistents izmanto to atbildēs, un tai ir atbildīgā persona, birkas, pārbaude un atļaujas tāpat kā jebkurai citai kartītei.

Jums vajadzīga API atslēga ar tvērumu cards:write un loma, kas var rakstīt mērķa kolekcijā (editor vai admin). Piemēri izmanto palīgfunkciju no Ātrās sākšanas.

Piemērotās operācijas izvēle

Visam, ko importējat vairāk nekā vienreiz, izmantojiet external_id. Tad katru importu var atkārtot: palaižot to vēlreiz, tiek atjauninātas tā izveidotās kartītes, nevis pievienotas kopijas.

Kartītes izveide vai aizstāšana pēc jūsu ID

PUT /v1/cards-by-external-id/{external_id} pieņem ieraksta ID jūsu sistēmā. Ja nevienai kartītei nav šī external_id, operācija izveido jaunu kartīti (201). Ja kartīte ar to ir, operācija aizstāj kartītes saturu un datus (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 notiek atkārtojumā:

• Saturs nav mainījies: jauna versija netiek veidota. Atbilde ir 200 ar "status": "skipped" un "reason": "unchanged". Pieprasījuma atkārtošana vienmēr ir droša, arī bez Idempotency-Key.
• Saturs ir mainījies: kartīte iegūst jaunu versiju un tiek indeksēta no jauna. Tās virsraksts, birkas, atbildīgā persona, kategorija un metadata iegūst nosūtītās vērtības; metadata tiek aizstāts kopumā.
• Kolekcija un mape tiek piemērotas tikai kartītes izveidē. Lai kartīti vēlāk pārvietotu, mainiet to ar PATCH /v1/cards/{card_id}.

Jauna versija noņem kartītes pārbaudi, tāpat kā jebkura satura izmaiņa: pārbaudītājs to apstiprina vēlreiz.

Teksta formāti

Gaidīt kartīti vai ne

Pēc noklusējuma pieprasījums atgriež atbildi, kad kartīti jau var atrast, ar "status": "ready" un kartīti laukā card. Tas aizņem no sekundes daļas īsam tekstam līdz minūtei vai vairāk garam failam.

Lielapjoma importiem nosūtiet "async": true. Atbilde pienāk uzreiz ar "status": "queued" un indeksēšanas darbu laukā job (ar tā job_id). Pārbaudiet darbu ar GET /v1/jobs/{job_id} vai sekojiet visiem darbiem straumē GET /v1/jobs/stream. Darbs beidzas ar status done, error vai canceled.

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

Faila augšupielāde

Faili tiek sūtīti multipart/form-data pieprasījumā laukā file. Sursa nolasa PDF, Word, Excel, PowerPoint, OpenDocument izklājlapas, CSV, Markdown, HTML, AsciiDoc, e-pastu (.eml), vienkāršu tekstu un izplatītus attēlu formātus. Tā pārbauda, vai faila nosaukums, deklarētais tips un saturs saskan, un neatbilstību noraida ar 415.

Lai izveidotu vai aizstātu faila kartīti pēc sava ID, nosūtiet failu uz to pašu 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"}'

Formā tags ir ar komatiem atdalīta virkne, bet metadata – JSON objekts, kas ierakstīts kā virkne. Jauna kartīte bez title par virsrakstu saņem faila nosaukumu.

Lai failu pievienotu vienreiz bez sava ID, izmantojiet POST /v1/cards ar to pašu formu un Idempotency-Key. Ja augšupielādējat failu, kas kolekcijā jau ir, tiek atgriezts "status": "skipped" ar "duplicate": true un esošās kartītes card_id, ja vien nenododat external_id.

Viena faila izmēru ierobežo instalācija (pēc noklusējuma 200 MB). Lielākus failus, kā arī nestabilos tīklos vispirms augšupielādējiet failu pa daļām.

Kartītes satura aizstāšana

Ja jums jau ir kartītes Sursas ID, PUT /v1/cards/{card_id}/content aizstāj tās tekstu vai failu un saglabā visu pārējo: atbildīgo personu, birkas, pārbaudītājus, pārbaudes intervālu un manuāli iestatītu kategoriju.

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 saturs vēlreiz atgriež "status": "skipped" ar "reason": "unchanged".
• Kartīte, kas pašlaik tiek indeksēta, atgriež 409 ar kodu cards.indexing_in_progress. Atkārtojiet pēc dažām sekundēm.
• Kartīti, kas nāk no avota, piemēram, savienotāja vai pielāgota avota, var mainīt tikai tās avotā: cards.managed_by_source.
• Atslēgai jābūt atļautam redzēt visu kartīti; daļēji redzama kartīte atgriež cards.content_whole_access.

Daudzu dokumentu imports

Cikls pa jūsu ierakstiem ar PUT /v1/cards-by-external-id/… ir vienkāršākais lielapjoma imports, un to var droši apturēt un palaist vēlreiz jebkurā brīdī. Lai tas būtu ātrs un ievērotu pieprasījumu biežuma limitu:

1. Nosūtiet "async": true, lai katrs pieprasījums atgrieztu atbildi, tiklīdz kartīte ir ievietota rindā.
2. Izpildiet dažus pieprasījumus paralēli (4–8) un palēniniet tempu, kad galvene RateLimit rāda, ka atlicis maz pieprasījumu. Sk. Pieprasījumu biežuma limiti un kvotas.
3. Pie 429 nogaidiet Retry-After; pie tīkla kļūdas vai 5xx atkārtojiet to pašu pieprasījumu. Atkārtojumi nekaitē.
4. Pierakstiet katra ieraksta external_id, kura apstrāde beidzas ar kļūdu, un beigās atkārtojiet šos ierakstus.

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 arhīvam ar failiem POST /v1/cards/archive ar vienu pieprasījumu pārvērš katru tajā esošo atbalstīto failu par kartīti. Operācija uzreiz atbild ar izpakošanas plānu (kuri faili kļūst par kartītēm, kuri tiek izlaisti un kāpēc) un darbu; GET /v1/archives/{job_id} ziņo rezultātu.

Importēto kartīšu atrašana un noņemšana

• Nolasiet kartīti pēc sava ID ar GET /v1/cards-by-external-id/{external_id}.
• Uzskaitiet viena importa kartītes ar metadatu filtru: GET /v1/cards?metadata[source]=helpdesk. Sk. Metadati.
• Dzēsiet kartīti ar DELETE /v1/cards/{card_id}.

Biežākās kļūdas