# Lähetä dokumentteja omista järjestelmistäsi Source: https://nordvec.com/fi/docs/guides/how-to/push-documents Luo tietolähde, lähetä dokumentteja siihen indeksointiin API-avaimella, valitse, ketkä voivat lukea niitä, ja keskeytä tai poista se, kun lähde muuttuu. Push-API indeksoi dokumentteja järjestelmistä, joille Nordvecilla ei ole liitintä: sisäisen wikin vienti, tikettiarkisto, muistiinpanojen tietokanta. Lähetät tekstin ja tiedon siitä, kuka saa lukea sitä. Nordvec tallentaa sen EU:hun, indeksoi sen ja tekee siitä haettavan ja siteerattavan kuten mitä tahansa muuta dokumenttia. Jokainen työnnetty dokumentti päätyy **tietolähteeseen**, nimettyyn säilöön työtilassasi, jonka työtilan ylläpitäjä luo ensin. Työntö, joka nimeää tietolähteen, jota ei ole olemassa tai joka on pysäytetty, hylätään. ## Luo tietolähde [#luo-tietolähde] Avaa **Työtilan asetukset > Tietolähteet** ja valitse **Luo tietolähde**. Työtilan ylläpitäjät ja omistajat voivat tehdä tämän. Henkilökohtaisessa työtilassa se olet sinä. | Kenttä | Huomautukset | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Nimi | Näkyy asetuslistassa. Enintään 200 merkkiä. | | Slug | Jokainen työntö nimeää tämän. Pienet kirjaimet, numerot, `-` ja `_`, alkaa kirjaimella tai numerolla, enintään 200 merkkiä. Sitä ei voi muuttaa myöhemmin. | Slugia `confluence-export` käytetään esimerkeissä alla. ## Luo indeksointiin API-avain [#luo-indeksointiin-api-avain] Push-pyynnöt tunnistautuvat **Indeksointi**-luokan API-avaimella, joka sisältää `index:write`-oikeuden. Lisää `index:status` seurantaan ja `index:delete` dokumenttien poistamiseen tai koko tietolähteen korvaamiseen. Luo avain kohdassa **Työtilan asetukset > API-avaimet**. Raaka-avain alkaa `nv_eu_idx_`-merkeillä ja näytetään vain kerran. Katso lisätietoja [Tunnistautuminen](/docs/guides/authentication). Jokainen pyyntö nimeää myös työtilasi tunnuksen `tenantId`, joka on työtilasi osoitteen tunnus sovelluksessa (`/w//...`), ja sen on oltava työtila, johon avain kuuluu. ## Työnnä yksi dokumentti [#työnnä-yksi-dokumentti] `/documents/push` luo dokumentin tai päivittää sen, jos dokumentti samalla `id`-tunnuksella on jo olemassa tietolähteessä. ```bash curl https://nordvec.com/api/v1/documents/push \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: page-4711-2026-09-28" \ -d '{ "tenantId": "YOUR_WORKSPACE_ID", "document": { "id": "page-4711", "title": "Travel expense policy", "datasource": "confluence-export", "body": { "mimeType": "text/markdown", "content": "# Travel expenses\n..." }, "permissions": {}, "sourceUrl": "https://wiki.example.com/pages/4711", "type": "policy" } }' ``` ```json { "documentId": "page-4711", "status": "queued", "updated": false } ``` * `id` on vakaa tunnuksesi dokumentille tietolähteen sisällä. Saman `id`-tunnuksen työntäminen uudelleen päivittää dokumentin. Muuttumaton sisältö tunnistetaan tiivisteensä perusteella eikä sitä indeksoida kahdesti. * `body.mimeType` on yksi `text/plain`, `text/markdown`, `text/html`, `application/pdf` tai Wordin, Excelin ja PowerPointin (`.docx`, `.xlsx`, `.pptx`) tyyppejä. Binäärisisältö lähetetään base64-koodattuna. * `sourceUrl` tulee "siirry lähteeseen" -linkiksi jokaisessa dokumentin sitaatissa. Jätä se pois uudelleentyönnössä säilyttääksesi tallennetun linkin tai lähetä `null` tyhjentääksesi sen. * `type` asettaa dokumentin `content_type`, jota haun ja listan suodattimet käyttävät. Koko pyynnön runko on rajoitettu 1 Mt:n kokoon, joten suuri tiedosto tai iso erä vastaa `413`-virheellä. Jaa se osiin. ## Valitse, kuka saa lukea dokumenttia [#valitse-kuka-saa-lukea-dokumenttia] `permissions` on pakollinen jokaisessa työnnössä, joten jakamispäätöstä ei koskaan tehdä jättämällä kenttä pois. Tietolähteessä, joka on näkyvissä työtilalle: | `permissions` | Kuka saa lukea dokumenttia | | ----------------------------------------- | ------------------------------------------------------------------ | | `{}` | Jokainen työtilan jäsen | | `{ "allowedUsers": ["ana@example.com"] }` | Vain luetellut henkilöt | | `{ "allowedGroups": ["GROUP_ID"] }` | Näiden työtilaryhmien jäsenet, sisältäen alaryhmät | | `{ "allowAllTenantMembers": false }` | Hylätään: dokumenttia, jota kukaan ei voi lukea, pidetään poistona | Muuttaaksesi dokumentin lukuoikeuksia lähettämättä sen sisältöä uudelleen, käytä `POST /documents/push/permissions`-metodia. Jo rajoitetun dokumentin tekeminen näkyväksi koko työtilalle vaatii lisäksi `index:acl-widen`-oikeuden, joten rutiinisynkronointi ei voi hiljaa kumota käsin asetettua rajoitusta. ## Työnnä erissä [#työnnä-erissä] `/documents/push/bulk` hyväksyy enintään 100 dokumenttia yhdelle tietolähteelle per kutsu. Vastaus laskee `accepted`- ja `rejected`-määrät ja antaa tuloksen dokumenttia kohden, joten yksi virheellinen dokumentti ei epäonnista koko erää. 1 Mt:n rungon raja koskee kutakin kutsua, joten jaa suuret lataukset useisiin kutsuihin saman `uploadId`-tunnuksen alla. ```bash curl https://nordvec.com/api/v1/documents/push/bulk \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "tenantId": "YOUR_WORKSPACE_ID", "uploadId": "nightly-2026-09-28", "datasource": "confluence-export", "documents": [ { "id": "page-4711", "title": "Travel expense policy", "datasource": "confluence-export", "body": { "mimeType": "text/plain", "content": "..." }, "permissions": {} } ] }' ``` ## Korvaa koko tietolähde [#korvaa-koko-tietolähde] Kun järjestelmäsi voi luetella kaiken, mitä tietolähteen tulisi sisältää, lähetä koko luettelo yhtenä **lähetysistuntona**. Istunnon päättyessä tietolähteestä poistetut dokumentit siirretään roskakoriin. Istunnot vaativat indeksointiin tarkoitetun API-avaimen, joka sisältää `index:delete`-oikeuden lisäksi `index:write`-oikeuden, koska istunnon päättyminen poistaa dokumentteja. Avain, jolla istunto avataan, on myös ainoa avain, jolla sitä voi jatkaa. 1. Lähetä ensimmäinen sivu koodilla `"isFirstPage": true`. Se on sivu `0`. 2. Lähetä jokainen seuraava sivu sen `pageIndex`:lla (`1`, `2`, ...), missä järjestyksessä tahansa. Kahdesti lähetetty sivu lasketaan kerran, joten uudelleenlähetys on aina turvallista. 3. Lähetä viimeinen sivu koodilla `"isLastPage": true` ja sen `pageIndex`:lla. Luettelo, joka mahtuu yhdelle sivulle, lähettää `isFirstPage`:n ja `isLastPage`:n yhdessä. Viimeisellä sivulla ei tarvitse olla dokumentteja. Jokainen sivu käyttää samaa `uploadId`-arvoa, ja jokainen vastaus sisältää istunnon edistymisen `upload`-kohdassa. Istunto päättyy vasta, kun kaikki sivut `0`-arvosta viimeiseen on vastaanotettu. Istunnon päättyessä roskakoriin siirretään jokainen dokumentti, jota mikään istunnon sivu ei maininnut ja joka oli olemassa ennen istunnon avaamista. Mikä tahansa muu push-toiminto tietolähteeseen istunnon aikana säilyttää mainitsemansa dokumentin: yksittäinen push, erä ilman istuntotietoja, käyttöoikeuksien päivitys tai muuttumattoman sisällön uudelleenlähetys. Roskakori säilyttää sinne siirretyt dokumentit 30 päivää. Dokumentin uudelleenlähettäminen palauttaa sen, samoin kuin koko istunnon palauttaminen (katso alla). Istunto, joka ei saa yhtään sivua 24 tunnin kuluessa, vanhenee ja päättyy poistamatta mitään. Hylätty sivu vastaa koodilla `409 Conflict`, ei kirjoita mitään, ja sen `data.reason` kertoo syyn: | `reason` | Toimenpide | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `upload_incomplete` | Lähetä `missingPageIndexes`-kohdassa luetellut sivut ja sen jälkeen viimeinen sivu uudelleen | | `deletion_confirmation_required` | Istunnon päättyminen siirtäisi roskakoriin yli 20 % tietolähteen dokumenteista. Jos tämä on oikein, lähetä viimeinen sivu uudelleen asettamalla `"confirmDeletions"`-arvoksi `wouldTombstone` | | `deletion_confirmation_too_large` | `confirmDeletions` on suurempi kuin dokumenttien määrä, joka tietolähteessä oli istunnon avautuessa. Lähetä odottamasi poistettavien dokumenttien määrä | | `upload_in_progress` | Tietolähteellä on avoin istunto. Jos se on avaimesi istunto, viimeistele se, odota sen vanhenemista tai aloita alusta asettamalla `"forceRestartUpload": true` ensimmäiselle sivulle. Jos toinen avain avasi sen, `forceRestartUpload` korvaa sen vasta, kun se ei ole vastaanottanut sivua tuntiin, `restartableAt`-kohdan ajanhetkestä lähtien | | `upload_expired`, `upload_missing`, `upload_restarted` | Istunto on poistunut. Aloita uusi istunto uudella `uploadId`-arvolla | | `upload_closed`, `upload_id_reused` | `uploadId` on käytetty. Käytä uutta avainta | | `page_index_required` | Avaimellasi on avoin istunto tässä tietolähteessä. Lähetä `pageIndex` sivun kanssa | Jos haluat jatkaa keskeytyksen jälkeen, lue istunto koodilla `GET /documents/push/upload?tenantId=...&datasource=...&uploadId=...` (oikeus `index:status`). Sen `missingPageIndexes` listaa vielä lähettämättömät sivut. ### Peru istunnon päättyminen [#peru-istunnon-päättyminen] Jos istunto poisti dokumentteja, joita sen ei olisi pitänyt poistaa, esimerkiksi koska lähettämäsi luettelo oli kesken, palauta ne yhdellä kutsulla: ```bash curl https://nordvec.com/api/v1/documents/push/upload/restore \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "tenantId": "YOUR_WORKSPACE_ID", "datasource": "confluence-export", "uploadId": "nightly-2026-09-28" }' ``` Istuntoa avannut avain voi palauttaa sen, ja myös Nordveciin kirjautunut työtilan ylläpitäjä voi palauttaa minkä tahansa avaimen avaaman istunnon. Jokainen istunnon sulkemisen roskakoriin siirtämä dokumentti palautuu sisällöllään, ja vastaus laskee ne: `restored` ovat taas käytössä, `purged` oli jo poistettu pysyvästi roskakorista, ja `skipped` olivat muuttuneet sulkemisen jälkeen (työnnetty uudelleen tai poistettu uudelleen) ja jätettiin sellaisinaan. Istunnon palauttaminen kahdesti vastaa ensimmäisen palautuksen lukumäärillä ja `"replayed": true`, ja laittaa jonoon kaikki palautetut dokumentit, jotka odottavat vielä indeksointia. Siksi palautuksen toistaminen, joka ei vastannut, on turvallista. Istunto voidaan palauttaa 35 päivän ajan sen sulkemisesta, ja niin kauan kuin roskakori sisältää vielä sen poistamia dokumentteja. Kielletty palautus vastaa `409 Conflict` ja sen `data.reason`:llä: | `reason` | Mitä se tarkoittaa | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `upload_not_closed` | Istuntoa ei ole suljettu, joten se ei poistanut mitään | | `upload_in_progress` | Tietolähteellä on avoin istunto. Palauta vasta, kun se on suljettu tai vanhentunut | | `restore_purged` | Yli 30 päivää on kulunut, ja roskakori on poistanut jokaisen dokumentin. Työnnä ne uudelleen | | `workspace_not_entitled` | Työtilan suunnitelma ei tällä hetkellä salli palautusta roskakorista | | `corpus_cap_exceeded` | Dokumenttien palauttaminen ylittäisi työtilan dokumenttirajan, joten yksikään ei palautunut. `data.wouldRestore` on kuinka monta tarvittaisiin ja `data.headroom` kuinka monta mahtuu. Vapauta tilaa, sitten palauta uudelleen | ## Seuraa indeksointia [#seuraa-indeksointia] Työntö vastaa heti, kun dokumentti on asetettu jonoon. Kysy sen edistymistä `GET /documents/push/status`-kutsulla (oikeus `index:status`), suodatettuna tietolähteen tai dokumenttitunnuksen perusteella. Dokumentti siirtyy tilasta `queued` tilan `processing` kautta tilaan `completed` tai tilaan `failed` virheellä `error`. ## Kun työntö hylätään [#kun-työntö-hylätään] Työntö, joka nimeää tuntemattoman tai pysäytetyn tietolähteen, vastaa `422 Unprocessable Content`-virheellä. Viesti nimeää slugin ja linkittää **Workspace settings > Datasources** -sivulle työtilassasi, ja virheen `data` kertoo syyn ja mitä tehdä: ```json { "defined": true, "code": "UNPROCESSABLE_CONTENT", "status": 422, "message": "Datasource \"confluence-export\" is paused and accepts no documents. A workspace admin resumes it under Workspace settings > Datasources: https://nordvec.com/w/YOUR_WORKSPACE_ID/workspace/settings?tab=datasources", "data": { "why": "The datasource \"confluence-export\" is paused", "fix": "Resume it at https://nordvec.com/w/YOUR_WORKSPACE_ID/workspace/settings?tab=datasources, then retry the push", "link": "https://nordvec.com/docs/guides/how-to/push-documents" } } ``` Älä yritä näitä automaattisesti uudelleen: ne onnistuvat vasta, kun ylläpitäjä luo tai jatkaa tietolähdettä. ## Poista dokumentti [#poista-dokumentti] `POST /documents/push/delete` (scope `index:delete`) poistaa työntämäsi dokumentin sen `datasource` ja `id` perusteella. Dokumentit, joiden työntämisen lopetat, eivät poistu itsestään: poista jokainen dokumentti, jonka käytöstä poistat, tai lähetä tietolähteen koko luettelo latausistuntona, kuten edellä on kuvattu. ## Pysäytä, jatka ja poista [#pysäytä-jatka-ja-poista] * **Pysäytä** hylkää jokaisen jatkotyönnön tietolähteeseen. Sen dokumentit pysyvät haettavina. Työntö, joka on jo kirjoituksessa pysäytyksen hetkellä, valmistuu. * **Jatka** hyväksyy työnnöt jälleen. * **Poista** poistaa tietolähteen ja kaikki siihen työnnetyt dokumentit sekä niiden hakukannan. Oman järjestelmäsi kopio säilyy, joten työntämällä uudelleen tietolähteen luomisen jälkeen ne palautuvat. Poistoa ei voi peruuttaa. Jos toinen ylläpitäjä on muuttanut tietolähdettä listan lataamisen jälkeen, toiminto hylätään ja lista latautuu uudelleen, joten päätät uudelleen sen perusteella, mikä on nyt voimassa. Jokainen luonti, pysäytys, jatkaminen ja poisto kirjataan työtilan tarkastuslokiin. Asetuslista näyttää, kenelle kukin tietolähde on näkyvissä. Kuka saa lukea työnnettyä dokumenttia, päätetään `permissions`:n perusteella, joka lähetetään sen mukana. Tietolähteen luominen, pysäyttäminen tai poistaminen ei koskaan laajenna pääsyä mihinkään. Työntöjen kirjoitukset ovat idempotentteja: toista sama `Idempotency-Key` jokaisella yhden kirjoituksen uudelleenyrittämällä, ja kaksoiskappale vastaa ensimmäisestä yrityksestä sen sijaan, että sitä sovellettaisiin kahdesti. Katso lisätietoja [Virheistä ja nopeusrajoituksista](/docs/guides/errors-and-rate-limits). ## Seuraavat vaiheet [#seuraavat-vaiheet]