Lähetä dokumentteja omista järjestelmistäsi

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.

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ä.

Slugia confluence-export käytetään esimerkeissä alla.

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. Jokainen pyyntö nimeää myös työtilasi tunnuksen tenantId, joka on työtilasi osoitteen tunnus sovelluksessa (/w/<workspace id>/...), ja sen on oltava työtila, johon avain kuuluu.

/documents/push luo dokumentin tai päivittää sen, jos dokumentti samalla id-tunnuksella on jo olemassa tietolähteessä.

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

{ "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.

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:

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.

/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.

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": {} }
    ]
  }'

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:

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äättyminenKopioi linkki tähän otsikkoon

Jos istunto poisti dokumentteja, joita sen ei olisi pitänyt poistaa, esimerkiksi koska lähettämäsi luettelo oli kesken, palauta ne yhdellä kutsulla:

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ä:

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.

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ä:

{
  "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ä.

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ä 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.