Süsteemi sünkroonimine kohandatud allikaga

Kohandatud allikas ühendab süsteemi, millel ei ole sisseehitatud konnektorit: teie wiki, piletisüsteemi, andmebaasi, ekspordi ükskõik kust. Teie kood saadab dokumendid Sursasse ja Sursa muudab need kaartideks kogus ja kaustades, mille jaoks allikas on seadistatud. Neil kaartidel on sama otsing, vastused, kontroll ja õigused nagu mis tahes muu allika kaartidel.

Erinevalt kaartide otse kirjutamisest peab kohandatud allikas arvet selle üle, mida olete saatnud. Täieliku sünkroonimise lõpus arhiveerib Sursa iga dokumendi, mida te ei saatnud, seega jõuavad teie süsteemis tehtud kustutamised Sursasse ilma lisatööta.

Allika seadistamine

Administraator loob allika Sursas jaotises Sources → New source → Custom source (allikad → uus allikas → kohandatud allikas) ja valib:

• kogu ja soovi korral selle kaartide jaoks kausta;
• kaustarežiimi: kõik kaardid valitud kaustas või alamkaustad, mis peegeldavad iga dokumendi välja path;
• õigused: kogu õigused või „as in the source“ (nagu allikas), kus iga dokument loetleb, kes seda näha tohib.

Allika lehel on näha selle ID; näited kasutavad ID-d 42.

Võtme valimine

Allikavõti on kõige turvalisem valik üksiku integratsiooni jaoks, eriti sellise, mis töötab kolmanda osapoole platvormil. Ulatusega import:write organisatsiooni võti sobib teenusele, mis toidab mitut allikat.

Mõlemad võtmed saadetakse ühtemoodi ja kõik push-lõpp-punktid asuvad tee /v1/push/sources/{source_id} all. Kontrollige võtit ja allika olekut päringuga GET /v1/push/sources/{source_id}:

curl https://api.sursa.com/v1/push/sources/42 \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY"

{"source_id": 42, "name": "Helpdesk articles", "documents": 1840, "open_sync": null}

Dokument

Välja content asemel võib üksik dokument kanda kuni 100 MB suurust faili päringus multipart/form-data: fail osas file, ülaltoodud väljad JSON-ina osas document. Väljade upload_id ja attachments osadena üleslaadimised luuakse organisatsiooni võtmega, millel on ulatus import:write, ja otstarbega import_attachment; allikavõti ei saa neid luua.

Kaks saatmisviisi

Otsesed uuendused sobivad süsteemidele, mis annavad teile teada igast muudatusest, näiteks veebihaak teie klienditoe süsteemist või samm Zapieris. Saatke dokument, kui see luuakse või seda muudetakse, ja kustutage see, kui see eemaldatakse:

Muudatustest saavad kaardid umbes minuti jooksul; mitu järjestikust muudatust töödeldakse koos.

Sünkroonimised sobivad regulaarseteks eksportideks: saadate kõik või kõik, mis muutus, ja Sursa viib andmed vastavusse. Selle juhendi ülejäänud osa käsitleb sünkroonimisi.

Täieliku sünkroonimise käivitamine

Sünkroonimisel on kolm sammu: avamine, saatmine ja sulgemine.

1. Avage

POST /v1/push/sources/{source_id}/syncs avab sünkroonimise ja tagastab selle numbri:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Idempotency-Key: sync-2026-10-24" \
  -H "Content-Type: application/json" \
  -d '{"type": "initial", "max_minutes": 180}'

{"sync_number": 7, "type": "initial", "status": "open", "opened_at": "2026-10-24T02:00:00Z",
 "expires_at": "2026-10-24T05:00:00Z", "pushed": 0, "removed": 0}

• type on allika esimese sünkroonimise puhul initial ja pärast esimese sünkroonimise lõpetamist incremental. Sünkroonimine tüübiga incremental enne ühegi sünkroonimise lõpetamist tagastab sources.push_initial_required.
• Korraga saab avatud olla ainult üks sünkroonimine: teine tagastab 409 sources.push_sync_open.
• Sünkroonimine on avatud max_minutes minutit (vaikimisi 60, kuni 1440). Pärast seda see aegub: midagi ei arhiveerita ja selle numbrit enam ei aktsepteerita. Valige aeg, mis on teie ekspordi kestusest tublisti pikem.

2. Saatke dokumendid

Saatke dokumendid kuni 500 dokumendi suuruste partiidena koos sünkroonimise numbriga. Partii keha on kuni 50 MiB; partiis olevad failid edastatakse väärtusena upload_id.

curl -X POST https://api.sursa.com/v1/push/sources/42/documents/batch \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Idempotency-Key: sync-7-batch-1" \
  -H "Content-Type: application/json" \
  -d '{
    "sync_number": 7,
    "documents": [
      {"external_id": "faq-shipping", "title": "Shipping", "content_type": "markdown",
       "content": "# Shipping\n\nWe ship worldwide within 5 days.", "path": ["Support"]},
      {"external_id": "faq-refunds", "title": "Refunds", "content_type": "html",
       "content": "<p>Refunds take 14 days.</p>", "path": ["Support", "Billing"],
       "permissions": {"groups": ["Support"]}, "metadata": {"article_id": "1042"}}
    ]
  }'

Vastuses on iga dokumendi tulemus samas järjekorras, milles need saatsite:

{
  "results": [
    {"external_id": "faq-shipping", "result": "unchanged", "status": "indexed", "card_id": "8c1d…", "version": "5e0f…"},
    {"external_id": "faq-refunds", "result": "updated", "status": "pending", "card_id": "3f2c…", "version": "a91b…"}
  ]
}

Vaikimisi rakendatakse partii iga dokumenti eraldi: üks vigane dokument ei peata teisi.

Dokumente, mis ei ole pärast viimast sünkroonimist muutunud, ei pea uuesti saatma. Kinnitage need ID järgi päringuga POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch, kuni 1000 ID-d päringu kohta, et täielik vastavusse viimine need alles jätaks:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs/7/touch \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ids": ["faq-contact", "faq-hours"]}'

3. Sulgege

POST /v1/push/sources/{source_id}/syncs/{sync_number}/close lõpetab sünkroonimise:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs/7/close \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "complete"}'

Sulgege olekuga failed alati, kui teie eksport peatub poolel teel: complete pärast osalist eksporti arhiveeriks kõik dokumendid, milleni te ei jõudnud. Sama sulgemise kordamine tagastab sama tulemuse.

Pärast sulgemist muudab Sursa dokumendid umbes minuti jooksul kaartideks. Allika lehel on näha iga sünkroonimine koos saadetud ja arhiveeritud dokumentide arvuga ning GET /v1/push/sources/{source_id}/syncs/{sync_number} tagastab samad loendurid.

Inkrementaalsed sünkroonimised

Täielike sünkroonimiste vahel saatke ainult muutunu:

1. Avage väärtusega "type": "incremental".
2. Saatke muutunud dokumendid ja pange eemaldatud dokumentide ID-d väljale deletes (vt allpool).
3. Sulgege olekuga complete_incremental.

Käivitage aeg-ajalt, näiteks kord nädalas, täielik sünkroonimine, et tabada kõik, mis inkrementaalsest käivitusest välja jäi.

Dokumentide kustutamine partiis

Partii võib koos kirjutatavate dokumentidega dokumente ka eemaldada. Loetlege nende ID-d väljal deletes:

{
  "sync_number": 8,
  "documents": [{"external_id": "faq-shipping", "title": "Shipping", "content": "…"}],
  "deletes": ["faq-old-returns", "faq-fax"]
}

Iga kustutatud ID saab väljal results oma kirje, mille result on deleted või, kui allikas sellist dokumenti ei ole, not_found. Sama ID uuesti kustutamine on ohutu.

Atomaarsed partiid

Mõni muudatus on mõttekas ainult koos teistega, näiteks dokument ja dokument, mis selle asendab. Saatke "atomic": true ja partii rakendatakse kas täielikult või üldse mitte: kui mõni dokument ei läbi valideerimist, ei rakendata partiist midagi ning vastus on 422 koodiga sources.push_batch_rejected ja iga dokumendi tulemusega väljal error.details.results: ebaõnnestunud dokumentidel on error, teistel skipped.

{"sync_number": 8, "atomic": true, "documents": […], "deletes": ["faq-old-returns"]}

Ilma väljata atomic rakendatakse partii dokumendi kaupa. Kasutage atomaarseid partiisid seotud muudatuste jaoks ja tavalisi partiisid hulglaadimiseks, kus üks vigane dokument ei tohiks ülejäänuid kinni hoida.

Iga dokumendi tulemuse kontrollimine

Partii vastus ütleb, kuidas iga dokument kirjutati. Kaardiks muutmine toimub hiljem, seega võib status olla veel pending. Sünkroonimise nende dokumentide leidmiseks, millest ei saanud kaarte:

curl "https://api.sursa.com/v1/push/sources/42/syncs/7/documents?status=failed" \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY"

Igal kirjel on external_id, title, status, card_id, version ja reason, ning loendit lehitsetakse parameetriga cursor. status võtab vastu ka väärtused pending, processing, indexed ja removed.

Küsimise asemel võite lasta endale ka teatada: sündmused import.sync_completed (sünkroonimine on suletud ja töödeldud, koos kokkuvõtlike arvudega) ja import.document_failed (dokumendist ei saanud kaarti, koos väärtusega reason) saabuvad veebihaagi kaudu ja sündmuste linti.

Korduskatsed

• Saatke iga päringuga POST päis Idempotency-Key. Sama võtmega korratud partii tagastab esimese tulemuse.
• Isegi ilma võtmeta ei muutu sama väärtusega external_id dokument kunagi teiseks kaardiks: selle tulemus on unchanged või updated.
• Kui protsess peatub sünkroonimise keskel, avage uus sünkroonimine pärast vana aegumist või sulgege vana olekuga failed, kui selle number on teil veel olemas, ja käivitage sünkroonimine uuesti.

Piirangud

Dokument, mis ületab allika dokumendilimiidi, ebaõnnestub partiis põhjusega limit_reached; üksiku dokumendi päring saab vastuse 409 koodiga sources.push_too_many_documents. Sageduspiirangud kehtivad nagu mis tahes muule päringule; vt Sageduspiirangud ja kvoodid.

Levinud vead