# Lähetä dokumentteja omista järjestelmistäsi
Source: https://nordvec.com/fi/docs/guides/how-to/push-documents#korvaa-koko-tietolähde

## 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 |