Siirtorajapinnan käyttöohjeet ja REST-rajapinnan kuvaus

Yleistä

• Siirtorajapinnan avulla voidaan siirtää Kansallisarkistoon arkistoitavaa digitaalista tietoaineistoa sekä näihin liittyviä kuvailevia kontekstimetatietoja.

• Hallinnollisia edellytyksiä kuvataan tarkemmin Kansallisarkiston sähköisen arkistoinnin palvelun sivuilla: Siirroista sopiminen | Kansallisarkisto.

• Tässä ohjeessa ohjeistetaan siirtorajapintaan kytkeytymistä, siirtorajapinnan käyttöä ja siirron toiminnallisuuksia rajapintasiirroissa

• Siirto tapahtuu suomi.fi -palveluväylän avulla, josta on oma ohjeistuksensa

Sapan siirtokäyttöliittymän kautta siirtäminen tapahtuu osoitteessa https://ka-sapa.arkisto.fi Siirtokäyttöliittymä on graafinen käyttöliittymä, jonka avulla käyttäjä voi siirtää tietoaineistoja ja näitä kuvailevia kontekstimetatietoja Kansallisarkistoon kaikissa siirtorakenteissa. Tässä ohjeessa ei käsitellä graafisen siirtokäyttöliittymän kautta tehtäviä siirtoja muutoin kuin silloin, kun vähintään tietoaineistot siirretään rajapinnan avulla.

Siirtoprosessikokonaisuus

Alla olevassa kuvassa esitetään siirron toiminnallinen prosessi

Tässä ohjeessa ohjeistetaan, miten eri vaiheet etenevät ja kerrotaan tarkemmin käytettävissä olevista rajapinnan kohteista eli endpointeista ja niiden vaatimuksista.

Hallinnolliset asiat

Jäljempänä oletetaan, että siirron valmistelevat/hallinnolliset vaiheet on suoritettu ja hallinnollisissa valmisteluissa on päädytty rajapintasiirtoon. Lisätietoja hallinnollisista prosesseista, sopimuksista ja siirtorakenteista löydät Kansallisarkiston kotisivujen Ohjepankista: https://kansallisarkisto.fi/ohjepankki#sapa

Kontekstimetatiedon normalisointi

Kontekstimetadatan normalisointia varten on olemassa kaksi tapaa: siirtokäyttöliittymä ja metadatakatalogi. Siirtokäyttöliittymässä kontekstimetatiedot normalisoidaan siirtäjän toimesta soveltaen tätä varten tehtyä työkalua, jos kyseessä on Sähke2-aineisto. Siirtokäyttöliittymään voidaan ladata olemassa olevaa Sähke2-kontekstimetatietoa ohjeistusten mukaisesti ja muokata näitä edelleen siirtoa varten.

Metadatakatalogi tähtää siihen, että kontekstimetatietojen siirto voidaan automatisoida. Tätä varten kontekstimetatiedot on ensin normalisoitava muotoon, jossa ne ovat koneluettavia ja siirrettävissä Kansallisarkiston taustajärjestelmiin.

Metadatakatalogin kuvaus ja esimerkkejä normalisoiduista kontekstimetatiedoista löytyy sivuilta Metadatakatalogin käyttöohjeet ja kuvaus ja Metadataesimerkit siirtoa varten.

Sähke2

Sähke2-siirrossa kontekstimetatiedot ovat tuotettuna siirtopaketin sisällä oleviin sahke.xml ja sahke_norm.xml -tiedostoihin. Sähke2-siirtopaketti ladataan Sapa-järjestelmään ennen tässä kuvattua kontekstimetatietojen luontia ja Sapa parsii näistä kontekstimetatiedot automaattisesti Kansallisarkiston metatietojärjestelmään.

Pääsääntöisesti Sapa-järjestelmä parsii kontekstimetatiedot suoraan Sähke2-siirtopaketista mutta tietyt asiat tulee tuottaa sahke.xml-tiedoston rinnalla lähetettävään “sahke_norm.xml”-tiedostoon. “sahke_norm.xml”-tiedoston rakenteen vaatimukset on kuvattu alla. Kuvausta tarkentavia esimerkkejä löytyy sivulta Metadataesimerkit siirtoa varten, kohdasta Sähke2.

Normalisoidun Sähke2-metadatan sisältävän “sahke_norm.xml”-tiedoston tulee olla rakenteeltaan muuten identtinen sahke.xml-tiedoston kanssa, mutta lisättynä seuraavilla asioilla:

1. välittömästi XML-deklaraation jälkeen XML-kommenttiblokki (<!-- -->), jossa esitetään koko siirtoerää koskevat asiat jäljempänä kuvatussa rakenteessa,

2. Restriction.SecurityReason-elementin teksti tulee korvata rajoituksen perusteena olevan lain tai sopimuksen ID-arvolla metadatakatalogin kohdasta access_restrictions.template_identifier. Jos rajoittavia kohtia on useita, näiden arvot erotetaan toisistaan pilkulla (,) tai puolipisteellä (;).

XML-kommenttiblokin rakenne:

• Tiedot tulee esittää avain-arvo-pareina siten, että

  • avain ja arvo erotetaan toisistaan kaksoispisteellä ja välilyönnillä “: “

  • parit erotetaan rivinvaihdolla

  • arvo on UUID tai ID Kansallisarkiston metadatakatalogista

• Esitettävät tiedot:

  • authorizing_entity → Käyttöluvan myöntäjä eli taho, jolla on valtuudet myöntää käyttölupa käyttörajoitettuun tietoaineistoon

  • owner_organization → Kuvailtavan tietoaineiston juridinen omistaja. Omistaja-tieto määräytyy pääsääntöisesti aineiston elinkaaren vaiheen mukaan. Kun tietoaineisto on säilytysvaiheessa, on omistaja pääsääntöisesti siirtävä viranomainen. Kun tietoaineisto on arkistovaiheessa, omistaja on Kansallisarkisto

  • description_language → Kontekstimetatietojen kieli

  • content_category → Sisällön luonne kuvaa missä elinkaaren vaiheessa viranomaisaineisto on:
    viranomaisaineisto-arkistovaihe: Viranomaisen tehtävien hoitamisesta syntynyt tietoaineisto, joka on siirtynyt arkistovaiheeseen.
    viranomaisaineisto-väilytysvaihe: Viranomaisen tehtävien hoitamisesta syntynyt tietoaineisto, joka on edelleen säilytysvaiheessa

  • otherid_casefile → Asiaa koskevan tunnisteen rooli, joka on esitetty sahke.xml:n OtherId-kentässä

  • otherid_record → Asiakirjaa koskevan tunnisteen rooli OtherId-kentässä

Sähke2 - XML-tiedostosta arkistokuvailun metatietovarantoon vietävät tiedot

Alla olevassa taulukossa on lueteltu kaikki sahke.xml-tiedoston elementit, joiden sisältö viedään Kansallisarkiston arkistokuvailun metatietovarantoon tietoaineistoa kuvailevana metatietona.

Alkuperäinen sahke.xml-tiedosto säilytetään KP-PAS-palvelussa. Käyttöä varten sahke.xml-tiedosto pilkotaan vastaanoton yhteydessä osiin siten, että jokaisesta CaseFile-osasta muodostuu oma “S2-asiakirja”-alayksikkönsä, joka sisältää asiaa koskevan asianhallinnan metadatan.

Taulukon rakenne on seuraava:

• sahke.xml ylätason elementti → sahke.xml-dokumentin osa, johon elementti kuuluu

• sahke.xml elementti → XML-elementti, jonka sisältö viedään metatietovarantoon

• Metatietovarannon kenttä → XML-elementin vastine arkistokuvailussa

• Rooli/Lisätieto → metatietoon liittyvä arkistokuvailun rooli tai muu lisätieto. Esim. CaseFile.Title viedään aineiston nimekkeeksi aina roolissa “Päänimeke”, Record.NativeId aina roolissa “Muu tunniste”.

Mikäli sahke.xml:n Record-taso sisältää useita Document-elementtejä, joilla kaikilla on sama UseType (esim. “Arkisto”), jokaisesta Document-elementistä muodostetaan lisäksi Record-alayksikön alle oma alayksikkönsä, nimeke muotoa “Tiedosto X”.

Näiden alayksikköjen tietoja ei ole listattu alla olevassa taulukossa. Document-elementti ei itsessään sisällä kohdetta kuvailevaa tietoa, joten muodostettavan alayksikön tiedot kopioidaan sen ylemmän tason Record-elementiltä.

Kontekstimetatiedon siirtäminen

Siirtopakettien siirtämisen edellytys on, että kuvailevat kontekstimetatiedot on tuotettu Kansallisarkiston metatietojärjestelmään.

Kuten yllä olevasta kuvasta voidaan havainnoida, on kontekstimetatietojen siirto rajapinnan avulla pakollista vain silloin, kun siirrettävä siirtopaketti on Sähke2 -siirtorakenteessa. Tämä johtuu siitä, että Sähke2 -siirtorakenne sisältää sekä kontekstimetatiedot että itse tiedostot. Muissa siirtorakenteissa siirto voidaan vaiheistaa siten, että ensin tuotetaan kuvailevat kontekstimetatiedot joko rajapinnan avulla (metatiedot tulee olla normalisoitu metadatakatalogin avulla) tai Sapan siirtokäyttöliittymän avulla osoitteissa https://ka-sapa.arkisto.fi tai https://sapa.arkisto.fi (Valtionhallinto).

Huomioithan, että kontekstimetatietojen siirtäminen rajapinnan avulla vaatii Sapan käyttöliittymästä noudettua Api-avainta. Api-avaimen hausta ja käytöstä sivulla on kirjoitettu enemmän kappaleessa Api-avainten nouto.

Alla olevassa taulukossa esitetään, miten eri siirtorakenteissa voidaan siirtää arkistoitavia tietoaineistoja kontekstimetatietoineen Kansallisarkistoon, kun siirtopakettien siirtoon käytetään siirtorajapintaa.

Siirron mahdollistava tunniste

Tunnistetta tarvitaan jo kontekstimetatietojen luonnissa, mikäli siirtopakettien lataamisen lisäksi myös metatiedot luodaan rajapinnan kautta.

Siirron mahdollistava tunniste on Sapa-palvelun antama, “urn:oid:”-alkuinen TransferOID. Tunniste on sama kuin kontekstimetatietojen luonnissa käytettävä tunniste. Siirtopakettien TUS-otsikoiden yhteydessä sen käyttö on pakollista, jotta siirtopaketit saadaan sidottua oikeaan siirtokokonaisuuteen.

Api-avainten nouto

Api-avainten nouto tapahtuu siirtokäyttöliittymässä. Edellytyksenä Api-avaimen noutoon on se, että hallinnollisessa vaiheessa sinut on roolitettu siirtokäyttöliittymässä oikein Kansallisarkiston toimesta.

API-avaimen käyttö siirtäjän liityntäpalvelimella

Edellä luotua API-avainta tarvitaan, kun liityntäpalvelimelta tehdään kutsuja Sapan rajapinnalle. Pyynnön kohteen eli Sapa-alustan rajapinnan endpointin sijainnin ja metodin lisäksi jokaisessa rajapintakutsussa pitää antaa seuraavat yleiset tiedot

• Todennus:

  • X-Road-liityntäohjelmiston asiakkaan sertifikaatti, PEM-formaatti

  • X-Road varmenneavain, PEM-formaatti

• Headerit:

  • X-Road asiakasalijärjestelmän tunniste (CLIENT-SUBSYSTEM), pyynnön lähettävän alijärjestelmän Client ID

  • Asiakkaan Sapassa-luoma API-avain

Pyynnön perusrakenne liityntäpalvelimelta toiselle on curl-ohjelmistolla seuraava:

curl
-E <XROAD-CLIENT-CERT>
--key <XROAD-CLIENT-KEY>
-X POST "<XROAD-SERVER><TARGET-SUBSYSTEM><API-PATH>"
-H "accept: application/json"
-H "X-Road-Client: <CLIENT-SUBSYSTEM>"
-H "X-Api-Key: <SAPA-APIKEY>"

Rajapintapyynnön osoite, edellisessä esimerkissä “-X POST” jälkeinen osio, koostuu tiedoista

• Kansallisarkiston liityntäpalvelin (XROAD-SERVER):
  https://ka-palveluvayla.kansallisarkisto.fi/r1/

• Alijärjestelmä (TARGET-SUBSYSTEM), johon pyyntö kohdistuu:
  FI/GOV/0245885-9/sapa/ws

• REST-rajapinnan kohde, esim.
  /api/latest/statuses/document_id

REST-rajapinnan kuvaus

Ajantasainen REST-rajapinnan kuvaus OpenAPI-muodossa löytyy Suomi.fi-liityntäkatalogista.

Testi: Sähköisen arkistoinnin palvelu - ws - Testiliityntäkatalogi

Tuotanto: Sähköisen arkistoinnin palvelu - ws - Testiliityntäkatalogi

Kontekstimetatietojen tallennus siirtoerään → POST /api/latest/context-metadata

Kontekstimetatiedot annetaan viestissä lomaketietona (multipart/form-data). Onnistuneessa vastauksessa esitetään tallennetut kontekstimetatiedot kokonaisuudessaan sisältäen niiden yksilöivän tunnisteen Sapa-järjestelmässä.

Alla lueteltujen kenttien lisäksi onnistuneessa palautusviestissä on myös muita kohtia. SAPA täyttää nämä automaattisesti kontekstimetatietojen käsittelyn edetessä, joten niihin ei tallenneta mitään rivin luonnin yhteydessä. Esim. “accepted_at”-kohtaan tallentuu aikaleima, jolloin kontekstimetatiedot on onnistuneesti siirretty ja tallennettu arkistokuvailun metatietovarantoon; “ahaa_content_id” → rivin saama tekninen tunniste metatietovarannossa. Lisäksi “parent_context_metadata_id” sekä “identifier_sahke”- ja “sahke”-alkuisia kohtia käytetään vain ja ainoastaan Sähke2-siirron käsittelyssä ja SAPA täyttää nämä automaattisesti taustalla Sähke2-paketin sisällön perusteella.

Alla pakolliseksi merkityt kohdat pitää sisällyttää sanomaan, jotta kontekstimetatietojen siirto metatietovarantoon ylipäätään onnistuu seuraavassa vaiheessa.

Jos esim. “parent_id” tai “ahaa_series_id” puuttuu sanomasta, kontekstimetatietorivi kyllä tallentuu onnistuneesti SAPAn taustakantaan mutta tietojen viimeistely pysähtyy virheeseen HTTP 400 - Bad Request.

Tietoja ei pysty muuttamaan lähetyksen jälkeen, joten niiden muoto kannattaa tarkistaa huolellisesti.

Viestin määreet

Palautusviesti normaalitilanteissa

• HTTP 200 OK – Onnistunut viesti, palautuksena annetaan lisätyt kontekstimetatiedot JSON-muodossa.

• HTTP 400 Bad Request – Viesti ei tue parametrejä.

• HTTP 403 Forbidden – Pääsy estetty, käyttäjällä ei ole oikeuksia tähän resurssiin.

• HTTP 405 Method Not Allowed – Viestissä väärä metodi (muu kuin POST).

• HTTP 409 Conflict – Metatieto on jo olemassa samalla arkistometatietojärjestelmän aineistotunnisteella, siirtopaketin paikallinen yksilöivä tunniste on jo käytössä samassa siirtoerässä tai aineistolla on jo digitaalisia ilmentymiä arkistometatietojärjestelmässä.

Onnistuneen palautusviestin runko

Alta löytyvän palautusviestin “metadata”-osioon on annettu esimerkkiarvoja, joiden on tarkoitus kuvata pakollisia metatietoja. Oikeassa palautusviestissä esitetyt arvot eivät ole välttämättä samoja.

{
  "data": {
    "accepted_at": "",
    "ahaa_content_id": "",
    "ahaa_series_id": "12345",
    "content_level": "volume",
    "fetched_from": "sapa",
    "has_digital_expressions": false,
    "id": "c7b7b899-d31d-412f-a54c-119f02f7b760",
    "include_in_transfer": "true",
    "local_transfer_id": "paketti001",
    "metadata_source": "sapa",
    "parent_context_metadata_id": "",
    "parent_id": "12345",
    "status": "approved",
    "transfer_contract_id": "",
    "transfer_oid": "urn:oid:1.2.246.582.200.134985728679348093805279867",
    "transfer_set_id": "82cf1b52-bf09-46d0-9fa0-a111a7140b3c",
    "metadata": {
      "access_restrictions": [],
      "confidential": "",
      "confidentiality_class": "9d204813-6ba0-3a8c-81ef-7516c6ef4a41",
      "content_category": "abe893c6-ead3-3d5b-a3d6-9985f73fb9d7",
      "content_dates_end": "2023-11-30",
      "content_dates_start": "2023-02-01",
      "content_type": "",
      "description": "",
      "description_language": "d3ee87b7-4948-3873-9a77-07d7672d4526",
      "description_phase": "",
      "identifier_analog": "",
      "identifier_local": "testi_siirtopaketti_01",
      "identifier_old_technical": "",
      "identifier_sahke_native_id": "",
      "identifier_sahke_other_ids": [],
      "languages": ["d3ee87b7-4948-3873-9a77-07d7672d4526"],
      "lifespan_phase": "",
      "order": "1",
      "owner_organization": "1474963028",
      "personal_data": "a3c39071-e76c-30d0-8218-44841fe63097",
      "processing_aids": "",
      "processing_notes": "",
      "protection_level": "",
      "related_preserved_content": "",
      "security_class": "",
      "security_class_2020": "7b74c211-f2ba-3db4-809d-0c3714817d36",
      "signature_description": "",
      "title_description": "",
      "title_end": "",
      "title_main": "Päänimeke",
      "title_start": "",
      "title_type": ""
    },
    "sahke_metadata": {
      "abstract": "",
      “access_restrictions”:  [],
      "custom": "",
      "description": "",
      "identifier_other_ids": [],
      "sahke_content_level": "",
      "sahke_documents_count": "",
      "subject": "",
    },
  },
  "status": "success"
}

Kontekstimetatietojen viimeistely → POST /api/latest/transfer-set/document_id/finalize

Kun kaikki siirtoerän siirtopaketteja koskevat kontekstimetatiedot on luotu ja tallennettu SAPAn taustakantaan, kontekstimetatiedot pitää vielä siirtää Kansallisarkiston arkistokuvailun metatietovarantoon. Tämä tapahtuu POST-metodilla endpointissa /api/latest/transfer-set/{document_id}/finalize.

Onnistuneen pyynnön vastausviestissä esitetään kontekstimetatietorivien yksilöivät tunnisteet ja niitä vastaavat arkistokuvailun metatietovarannon tekniset tunnisteet.

Kaikilla siirtoerän kontekstimetatietoriveillä pitää olla vähintään pakolliset metatiedot ja rivin status “approved”.

Viestin määreet

Palautusviesti normaalitilanteissa

• HTTP 200 OK – Onnistunut viesti, vastauksena annetaan JSON-listana, jossa siirtopakettien yksilöivät tunnisteet on yhdistetty niitä vastaaviin arkistokuvailun metatietovarannon teknisiin tunnisteisiin.

• HTTP 400 Bad Request – Viesti ei tue parametrejä.

• HTTP 404 Not found - Siirtoerän tunnisteella ei löytynyt siirtoeriä tai tunnisteessa virhe.

• HTTP 405 Method Not Allowed – Viestissä väärä metodi (muu kuin POST).

• HTTP 409 Conflict – Kontekstimetatietorivi on muussa tilassa kuin “approved” tai sen sisällöstä puuttuu pakollisia tietoja (esim. aineiston omistajatieto, owner_organization on tyhjä)

Onnistuneen palautusviestin runko

{
  "data": {
    "identifiers": [
      {
        "ahaa_id": "AHAA id1",
        "local_id": "local id1"
      },
      {
        "ahaa_id": "AHAA id2",
        "local_id": "local id2"
      }
    ]
  },
  "status": "success"
}

Siirtopakettien siirto

Siirtopakettien lataus Sapan käsittelyyn rajapinnan kautta tapahtuu seuraavasti:

1. Siirtopaketille varataan tila Sapasta eli lähetys alustetaan
   POST /api/latest/uploads → vastauksen headereissa siirtopaketin resurssin yksilöivä resource_id

2. Siirtopaketti lähetetään osissa TUS-protokollan avulla käyttäen edellä saatua tunnistetta
   PATCH /api/latest/uploads/resource_id

3. PATCH-pyyntöjen välissä tiedoston latauksen edistymistä voi kysellä HEAD-metodilla samasta endpointista kuin edellisessä kohdassa. Vastauksen otsikot sisältävät tiedon siirron koosta Sapa-alustalla, jota voi käyttää esim. lähetyksen valmistumisen prosenttiosuuden laskemiseen
   HEAD /api/latest/uploads/resource_id

4. Kun siirtopaketti on kokonaisuudessaan lähetetty, lähetys tulee vielä viimeistellä, jolloin Sapan prosessointi käynnistyy
   POST /api/latest/transfers/resource_id → vastauksen rungossa siirtoerän käsittelyn yksilöivä tunniste id, joka esiintyy ohjeessa myöhemmin nimellä document_id.

5. Sapan siirtopaketin käsittelyn tilaa voi kysellä endpointista
   GET /api/latest/statuses/document_id → oleellinen kohta vastauksen rungossa on data.status, joka sisältää käsittelyn tilan tai lopputuloksen. Mahdolliset arvot on lueteltu alempana endpointin tarkemman kuvauksen kohdalla.

Sapa tekee useita eri tarkistuksia sekä siirtopaketin rakenteelle että tiedostoille ja, mikäli paketti läpäisee kaikki tarkistukset, lähettää SIP-version (Submission Information Package) Kulttuuriperintö-PAS-järjestelmään. Kun KP-PAS on käsitellyt siirtopaketin, palautuu tästä tieto - hyväksytty tai hylätty - Sapaan ja paketin käsittely päättyy.

Lähetyksen alustaminen, POST /api/latest/uploads

Sanoman otsikossa pitää antaa lähetettävää tiedostoa kuvailevaa teknistä metatietoa, mm. tiedoston nimi ja siirtorakenteen tyyppi. Upload-Metadata tiedon rakenteen kuvaus ja esimerkit löytyvät tämän sivun lopusta kohdasta “Upload-Metadata esimerkkejä”.

Upload-Metadata-tiedon pitää olla täsmälleen esimerkeissä ja alla kuvatussa muodossa. Tiedossa ei saa käyttää esimerkiksi useita välilyöntejä erottamaan avainta ja sen arvoa.

Viestin määreet

Viestissä annetaan ainoastaan tietoa pyynnön otsikossa. Palautusviesti sisältää myös ainoastaan tietoa otsikossa. Pyynnön otsikossa on annettava seuraavat tiedot avain-arvo -pareina:

• Tus-Resumable – TUS-protokollan versio, aina “1.0.0”

• Upload-Length – Siirtopakettitiedoston koko tavuina

• Upload-Metadata – Lähetyksen metatiedot
  Lähetyksen metatiedot annetaan avain-arvopareina siten, että

  • avaimen nimi on plain-tekstiä,

  • arvo esitetään Base64-enkoodattuna,

  • avain ja arvo erotetaan toisistaan välilyönnillä ja

  • parit erotetaan toisistaan pilkulla (,)

Palautusviesti normaalitilanteissa

• HTTP 201 Created – Onnistunut alustaminen. Palautusviestissä annetaan vain otsikko, ei runkoa. Otsikossa on annettu osoite, johon tiedostoa voi alkaa lähettämään.

• HTTP 400 Bad Request – Annetut metatiedot eivät ole valideja, tai annettu tiedoston koko on 0.

• HTTP 403 Forbidden – Pääsy estetty, käyttäjällä ei ole oikeuksia tähän resurssiin.

• HTTP 405 Method Not Allowed – Viestissä väärä metodi (muu kuin POST tai OPTIONS).

• HTTP 412 Precondition Failed – Annettua TUS-protokollan versiota ei tueta.

• HTTP 503 Service Unavailable – SAPA-palvelu ei kykene vastaanottamaan lähetystä.

Onnistuneen palautusviestin otsikon tiedot

• Location – URL-osoite, resurssin tunniste, johon itse siirtopaketti voidaan lähettää

• Tus-Resumable – SAPA-palvelun tuetut TUS-protokollan versiot

Location-vastaus on muodossa https://sapa.arkisto.fi/api/latest/uploads/{resource_id} tai https://ka-sapa.arkisto.fi/api/latest/uploads/{resource_id}. Resource_id pitää parsia tämän URLin lopusta, sillä tiedoston lähetyksen yhteydessä headereissa pitää olla vain resource_id (ei koko URLia).

Tiedoston lähettäminen, PATCH /api/latest/uploads/resource_id

Kun tiedoston lähetys on alustettu onnistuneesti, siirtopakettia voi alkaa lähettämään SAPA-alustalle. Lähetys tapahtuu TUS-protokollan avulla, joka pilkkoo lähetettävän tiedoston osiin (oletuksena 1Mt) ja lähettää nämä jonossa vastaanottavaan järjestelmään. TUS-protokollan käyttö mahdollistaa tiedoston lataamisen jatkamisen tilanteessa, jossa yhteys siirtävän ja vastaanottavan järjestelmien välillä katkeaisi odottamattomasti.

Viestin määreet

resource_id – TUS-protokollan generoima resurssin tunniste. Osoite, joka on annettu lähetyksen alustamisen palautusviestin otsikossa, Location-avaimen alla.

Viestin rungossa annetaan siirtopaketti osina application/octet-stream mediatyyppinä.

Lisäksi pyynnön otsikoissa on annettava seuraavat tiedot:

• Tus-Resumable – TUS-protokollan versio

• Upload-Offset – Viestin rungossa lähetettävän osan etäisyys tavuina paketin alusta. Tämä kertoo mihin kohtaan tiedostoa, lähetty osa kuuluu. Jos lähetys keskeytetään, tämän arvon avulla voidaan jatkaa lähetystä siitä mistä jäätiin.

Palautusviesti normaalitilanteissa

• HTTP 204 No Content – Onnistunut lähetys, siirtopaketin osa lähetettiin onnistuneesti.

• HTTP 400 Bad Request – Annetun osan koko on 0.

• HTTP 403 Forbidden – Pääsy estetty, käyttäjällä ei ole oikeuksia tähän resurssiin.

• HTTP 404 Not Found – Annettua resurssia ei löytynyt.

• HTTP 405 Method Not Allowed – Viestissä väärä metodi (muu kuin PATCH tai HEAD).

• HTTP 409 Conflict – Annettu Upload-Offset tieto ei ole validi.

• HTTP 412 Precondition Failed – Annettua TUS-protokollan versiota ei tueta.

• HTTP 415 Unsupported Media Type – Rungossa lähetettävän datan formaatti ei ole tuettu.

Onnistuneen palautusviestin otsikon tiedot

• Upload-Offset – Lähetettyjen osien tavujen kokonaismäärä, siirtopaketin tämänhetkinen koko SAPA-palvelussa

• Tus-Resumable – SAPA-palvelun tuetut TUS-protokollan versiot

Kun Upload-Offset vastaa lähetyksen alustamisessa annettua siirtopaketin tiedoston kokoa, lähetys on valmis ja siirtopaketti on kokonaisuudessaan siirretty onnistuneesti SAPA-palveluun. Tämän jälkeen lähetys pitää viimeistellä, jotta SAPA-palvelu ottaa siirtopaketin käsittelyyn.

Lähetyksen tilan kysely, HEAD /api/latest/uploads/resource_id

Lähetyksen alustamisen jälkeen ja siirtopaketin osien lähetyksen välissä lähetyksen tilaa voi kysellä tästä kohteesta. Vastauksen otsikoissa esitetään mm. tieto siitä, kuinka paljon siirtopakettia on jo otettu vastaan. Tietoa voi hyödyntää esimerkiksi lähetyksen valmistumisen prosenttiosuuden laskennassa. Parametri resource_id on sama kuin edellä paketin lähetyksessä tarvittava tunniste.

Viestin määreet

resource_id – TUS-protokollan generoima resurssin tunniste. Osoite, joka on annettu lähetyksen alustamisen palautusviestin otsikossa, Location-avaimen alla.

Viestissä runko on tyhjä. Pyynnön otsikoissa on annettava seuraavat tiedot:

Tus-Resumable – TUS-protokollan versio

Palautusviesti normaalitilanteissa

• HTTP 200 Ok – Onnistunut kysely.

• HTTP 403 Forbidden – Pääsy estetty, käyttäjällä ei ole oikeuksia tähän resurssiin.

• HTTP 404 Not Found – Annettua resurssia ei löytynyt.

• HTTP 405 Method Not Allowed – Viestissä väärä metodi (muu kuin PATCH tai HEAD).

• HTTP 412 Precondition Failed – Annettua TUS-protokollan versiota ei tueta.

Onnistuneen palautusviestin otsikon tiedot

• Cache-Control – Tieto kuinka välimuistia tule käsitellä, arvo on aina ”no-store”.

• Upload-Offset – Lähetettyjen osien tavujen kokonaismäärä, siirtopaketin tämän hetkinen koko SAPA-palvelussa

• Tus-Resumable – SAPA-palvelun tuetut TUS-protokollan versiot

• Upload-Metadata – Alustuksessa annettu metatieto

• Upload-Length – Alustuksessa ilmoitettu lähetyksen koko tavuina

Lähetyksen viimeistely, POST /api/latest/transfers/resource_id

Kun siirtopaketti on lähetetty kokonaisuudessaan SAPA-palveluun, lähetys pitää vielä viimeistellä ennen kuin SAPAn prosessointi käynnistyy. Palautusviestissä annetaan lähetyksen yksilöivä tunniste SAPAn työvuossa (document_id), joka on sama kuin edellä käytetty resource_id.

Viestin määreet

resource_id – TUS-protokollan generoima resurssin tunniste. Osoite, joka on annettu lähetyksen alustamisen palautusviestin otsikossa, Location-avaimen alla.

Palautusviesti normaalitilanteissa

• HTTP 200 OK – Onnistunut viesti, viestin rungossa annetaan SAPA-palvelun generoima siirtopaketin tunniste.

• HTTP 403 Forbidden – Pääsy estetty, käyttäjällä ei ole oikeuksia tähän resurssiin.

• HTTP 404 Not Found – Annettua resurssia ei löytynyt.

• HTTP 405 Method Not Allowed – Viestissä väärä metodi (muu kuin POST).

• HTTP 409 Conflict – Resurssi ei ole vielä valmis, siirtopakettia ei ole vielä siirretty kokonaisuudessaan.

Onnistuneen palautusviestin runko

{
  "data": {
    "object": {
      "id": "Unique document ID", 
    }
  },
  "status": "success"
}

id on SAPA-palvelun generoima siirtopaketin yksilöivä tunniste. Tunnisteella haetaan paketin tiedot statuskyselyissä.

Siirtopaketin käsittelyn tilan kysely, GET /api/latest/statuses/document_id

Kun siirtopaketti on ladattu kokonaisuudessaan Sapa-alustalle ja lähetys on viimeistelty, Sapan prosessointi käynnistyy. Käsittelyn tilaa ja edistymistä voi kysellä tästä endpointista.

Viestin määreet

document_id – Siirtopaketin yksilöivä tunniste SAPA-palvelussa.

Palautusviesti normaalitilanteissa

• HTTP 200 OK – Onnistunut viesti, palautuksena annetaan löydetyn siirtopaketin tiedot JSON-muodossa.

• HTTP 400 Bad Request – Viesti ei tue parametrejä.

• HTTP 403 Forbidden – Pääsy estetty, käyttäjällä ei ole oikeuksia tähän resurssiin.

• HTTP 404 Not Found – Pakettia ei löytynyt.

• HTTP 405 Method Not Allowed – Viestissä väärä metodi (muu kuin GET).

Onnistuneen palautusviestin runko

{
  "data": {
    "ahaa_id": 1234567,
    "ahaa_ids": [{
      "level": "volume",
      "value": 1234567
    }],
    "aip_id": "unique-digital-preservation-aip-id",
    "filename": "transfer.tar.gz",
    "id": "unique-transfer-id",
    "local_transfer_id": "mytransfer1",
    "mets_objid": "unique-mets-objid",
    "package_type": "sahke2",
    "processing_end_timestamp": "Fri, 19 Jul 2019 11:50:12 GMT",
    "processing_start_timestamp": "Fri, 19 Jul 2019 11:50:12 GMT",
    "reports": {
      "html": "/url/for/downloading/report/in/html",
      "xml": "/url/for/downloading/report/in/xml"
    },
    "status": "transfer received",
    "tasks": {
     ... 
    },
    "timestamp": "Fri, 19 Jul 2019 11:50:12 GMT",
    "transfer_oid": "1.2.3.4.5",
    "transfer_set_id": "transfer-set-uuid",
    "transfer_size": 1000,
    "transfer_type": "digitization"
  },
  "status": "success"
}

Tulosalkio sisältää kaikki samat tiedot kuin siirtopaketin haku ja listaustiedot. Niiden lisäksi näytetään seuraavat tiedot:

• aip_id – Pitkäaikaissäilytettävän paketin tunniste PAS-palvelussa.

• filename – Paketin tiedostonnimi.

• mets_objid – Luodun siirtopaketin tunniste PAS-palvelussa.

• package_type – Siirtopaketin pakettityyppi.

• tasks – Työvuon vaiheet. Tasks sisältää tiedot kaikista suoritetuista vaiheista, niiden aikaleimoista ja vaiheiden tuloksien kuvaukset:

• result – Kertoo, suoritettiinko vaihe onnistuneesti vai ei; arvo voi olla joko ”success” tai ”failure”.

• timestamp – Vaiheen suorittamisen aikaleima.

• messages – Vaiheen tuloksen kuvaus.

• Ahaa-ids listaa jokaisen arkistokuvailun metatietovarannon teknisen tunnisteen, joka liittyy paketin sisältöihin:

  • level – Aineistotaso, “volume” = Arkistoyksikkö, “sub-volume” = Alayksikkö

  • value – Metatietovarannon tekninen tunniste

Mikäli paketti on hylätty, sisältää tulosalkio seuraavan tiedon:

failure – Virheviesti hylätyille paketeille.

Upload-Metadata esimerkkejä

Siirtopakettia koskevat tiedot tulee antaa siirtopaketin lähetyksen alustuksen yhteydessä osana
POST /api/latest/uploads -rajapintakutsua. Tietojen esityksen järjestyksellä ei ole merkitystä mutta seuraavia sääntöjä pitää noudattaa:

Arvot pitää esittää Base64-koodattuna.

Avain ja arvo erotetaan välilyönnillä, avain-arvoparit erotetaan toisistaan pilkulla ilman muita merkkejä. Alla olevissa esimerkeissä on käytetty rivinvaihtoa luettavuuden parantamiseksi.

Lisäksi siirtopaketin MD5-tarkistesumman arvon pitää olla pienillä kirjaimilla ennen Base64-koodausta.

Tarvittavat tiedot:

• filename → siirtopaketin nimi, myös tiedostopääte

• package_checksum → siirtopaketin MD5-tarkistesumma

• package_type → Sapa-siirtorakenteen nimi

• transfer_oid → Siirtoerän “urn:oid:”-alkuinen tunniste

• Vain Sähke2-aineistoille:

  • ahaa_series_id → Sapa-palvelun antama ylätason tekninen tunniste, johon siirtopaketti liittyy

• Digitoiduille kuva-aineistoille lisäksi:

  • digitization_rationale → Kansallisarkiston laatukriteerit

filename cGFrZXR0aV9lc2ltZXJra2kudGFy,
package_checksum MDhmNDNkMjcxZDliYmY2N2EyZjAyYmQ4MDc5YTIwNDY=,
package_type Y3VzdG9tZXItZGlnaXRpemF0aW9u,
transfer_oid dXJuOm9pZDoxLjIuMjQ2LjU4Mi4yMDAuMTM0OTg1NzI4Njc5MzQ4MDkzODA1Mjc5ODY3
digitization_rationale ZGU2NTAwNWMtZWUyZi0zYmNmLThkNzctODQ5MzY0MWNiYzA5

Attribuutti             | Arvo plain-tekstinä
------------------------|---------------------------------------
filename                | paketti_esimerkki.tar
package_checksum        | 08f43d271d9bbf67a2f02bd8079a2046
package_type            | customer-digitization
transfer_oid            | urn:oid:1.2.246.582.200.134985728679348093805279867
digitization_rationale  | de65005c-ee2f-3bcf-8d77-8493641cbc09 (2019 vaatimukset)

filename cGFrZXR0aV9lc2ltZXJra2kudGFy,
package_checksum MDhmNDNkMjcxZDliYmY2N2EyZjAyYmQ4MDc5YTIwNDY=,
package_type ZGlnaXRhbC1hcmNoaXZhbC1jb250ZW50,
transfer_oid dXJuOm9pZDoxLjIuMjQ2LjU4Mi4yMDAuMTM0OTg1NzI4Njc5MzQ4MDkzODA1Mjc5ODY3

Attribuutti             | Arvo plain-tekstinä
------------------------|---------------------------------------
filename                | paketti_esimerkki.tar
package_checksum        | 08f43d271d9bbf67a2f02bd8079a2046
package_type            | digital-archival-content
transfer_oid            | urn:oid:1.2.246.582.200.134985728679348093805279867

filename cGFrZXR0aV9lc2ltZXJra2kudGFy,
package_checksum MDhmNDNkMjcxZDliYmY2N2EyZjAyYmQ4MDc5YTIwNDY=,
package_type ZGlhcnktZHVtcA==,
transfer_oid dXJuOm9pZDoxLjIuMjQ2LjU4Mi4yMDAuMTM0OTg1NzI4Njc5MzQ4MDkzODA1Mjc5ODY3

Attribuutti             | Arvo plain-tekstinä
------------------------|---------------------------------------
filename                | paketti_esimerkki.tar
package_checksum        | 08f43d271d9bbf67a2f02bd8079a2046
package_type            | diary-dump
transfer_oid            | urn:oid:1.2.246.582.200.134985728679348093805279867

ahaa_series_id MTIzNDU2Nzg5MA==,
filename cGFrZXR0aV9lc2ltZXJra2kudGFy,
package_checksum MDhmNDNkMjcxZDliYmY2N2EyZjAyYmQ4MDc5YTIwNDY=,
package_type c2Foa2Uy,
transfer_oid dXJuOm9pZDoxLjIuMjQ2LjU4Mi4yMDAuMTM0OTg1NzI4Njc5MzQ4MDkzODA1Mjc5ODY3

Attribuutti             | Arvo plain-tekstinä
------------------------|---------------------------------------
ahaa_series_id          | 1234567890
filename                | 1234567890.tar
package_checksum        | 08f43d271d9bbf67a2f02bd8079a2046
package_type            | sahke2
transfer_oid            | urn:oid:1.2.246.582.200.134985728679348093805279867