Bruksanvisning för överförings-API och beskrivning av REST-gränssnittet
Allmänt
Med hjälp av överföringsgränssnittet kan digitalt informationsmaterial som ska arkiveras och tillhörande beskrivande kontextmetadata överföras till Riksarkivet.
De administrativa förutsättningarna beskrivs närmare på webbplatsen för Riksarkivets tjänst för elektronisk arkivering: Avtal om överföring | Riksarkivet.
Den här bruksanvisningen innehåller instruktioner om hur du ansluter till överföringsgränssnittet, hur du använder överföringsgränssnittet och överföringens funktioner vid gränssnittsöverföringar.
Överföringen sker via suomi.fi-informationsleden, som har sina egna anvisningar.
Överföringar genom Sapas överföringsgränssnitt görs på https://ka-sapa.arkisto.fi. Överföringsgränssnittet är ett grafiskt användargränssnitt som gör det möjligt för användaren att överföra informationsmaterial och kontextuell metadata som beskriver materialen till Riksarkivet i vilken överföringsstruktur som helst. Den här bruksanvisningen innehåller inte instruktioner om överföringar via det grafiska överföringsgränssnittet, utom i de fall då åtminstone informationsmaterialet överförs via gränssnittet.
Överföringsprocessen i sin helhet
Figuren nedan visar den operativa processen för överföringen.

De här instruktionerna beskriver hur du går tillväga i de olika stegen och ger mer information om de tillgängliga gränssnittsobjekten, det vill säga endpoints, och kraven för dem.
Administrativa frågor

Nedan förutsätts att de förberedande/administrativa stegen i överföringen har slutförts och att de administrativa förberedelserna har resulterat i en gränssnittsöverföring. För mer information om administrativa processer, avtal och överföringsstrukturer, se Instruktionsbanken på Riksarkivets webbplats: https://kansallisarkisto.fi/sv/instruktionsbank#digitalarkivering
Normalisering av kontextmetadata
Det finns två sätt att normalisera kontextmetadata: överföringsgränssnittet och metadatakatalogen. I överföringsgränssnittet normaliseras kontextmetadata av överföraren med hjälp av ett särskilt verktyg, när det gäller Sähke2-material. Befintliga Sähke2-kontextmetadata kan laddas upp till överföringsgränssnittet enligt instruktionerna och redigeras ytterligare inför överföringen.
Metadatakatalogen syftar till att automatisera överföringen av kontextmetadata. För att göra det måste kontextmetadatan först normaliseras till ett format som är maskinläsbart och kan överföras till Riksarkivets backend-system.
För en beskrivning av Metadatakatalogen och exempel på normaliserade kontextmetadata, se Bruksanvisning för och beskrivning av Metadatakatalogen och Exempel på metadata för överföring.
Sähke2
Vid Sähke2-överföring produceras kontextmetadata i sahke.xml- och sahke_norm.xml-filerna i överföringspaketet. Sähke2-överföringspaketet laddas upp till Sapa före genereringen av kontextmetadata som beskrivs här sker, och Sapa plockar automatiskt ut kontextmetadata från dem till Riksarkivets metadatasystem.
I regel plockar Sapa ut kontextmetadata direkt från Sähke2-överföringspaketet, men vissa saker måste produceras i filen ”sahke_norm.xml” som skickas tillsammans med filen sahke.xml. Kraven på strukturen i filen ”sahke_norm.xml” beskrivs nedan. För mer detaljerade exempel på beskrivningen, se sidan Exempel på metadata för överföring, under Sähke2.
Filen ”sahke_norm.xml” som innehåller normaliserad Sähke2-metadata ska i övrigt ha samma struktur som filen sahke.xml, men med följande tillägg:
Ett XML-kommentarblock (<!-- -->), omedelbart efter XML-deklarationen, som anger vad som är relevant för hela överföringsposten i den struktur som beskrivs nedan.
Texten i elementet Restriction.SecurityReason ska ersättas med ID-värdet för den lag eller det avtal som begränsningen baseras på från access_restrictions.template_identifier i metadatakatalogen. Om det finns flera begränsningar separeras deras värden med ett kommatecken (,) eller semikolon (;).
Struktur för XML-kommentarblocket:
Informationen ska presenteras i nyckel-värde-par på så sätt att
nyckeln och värdet separeras med ett kolon och ett mellanslag ”: ”
par separeras med radbrytningar
värdet är UUID eller ID ur Riksarkivets metadatakatalog.
Information som ska presenteras:
authorizing_entity → Beviljaren av användningstillstånd, det vill säga den part som är behörig att bevilja användningstillstånd för informationsmaterial med användningsbegränsning.
owner_organization → Den juridiska ägaren till informationsmaterialet som beskrivs. I regel bestäms ägarinformationen av uppgifternas fas i livscykeln. När informationsmaterialet befinner sig i lagringsfasen är ägaren i allmänhet den överförande myndigheten. När informationsmaterialet befinner sig i arkivfasen är ägaren Riksarkivet.
description_language → Språk för kontextmetadatan
content_category → Innehållets karaktär beskriver vilken fas i livscykeln som myndighetsmaterialet befinner sig i:
myndighetsmaterial-arkiveringsfas: Informationsmaterial som uppkommit vid skötseln av myndighetens uppgifter och som har övergått till arkiveringsfasen.
myndighetsmaterial-lagringsfas: Material som uppkommit vid skötseln av myndighetens uppgifter och som fortfarande befinner sig i lagringsfasen.otherid_casefile → Rollen för den beteckning för ärendet som anges i rutan OtherId i sahke.xml
otherid_record → Rollen för den beteckning för dokumentet som anges i rutan OtherId
Sähke2 – Information som exporteras från en XML-fil till metadatalagret för arkivbeskrivning
I tabellen nedan listas alla element i sahke.xml-filen vars innehåll exporteras till Riksarkivets metadatalager i form av metadata som beskriver informationsmaterialet.
Den ursprungliga sahke.xml-filen lagras i tjänsten Kulturarv-LDB. För användning delas sahke.xml-filen upp i delar vid mottagandet, så att varje CaseFile-del är en separat ”S2-dokument”-underenhet som innehåller relevant metadata för ärendehantering.
Tabellen är uppbyggd på följande sätt:
sahke.xml-element på högsta nivå → den del av sahke.xml-dokumentet som elementet hör till
sahke.xml-element → XML-element vars innehåll exporteras till metadatalagret
Ruta för metadatalager → XML-elementets motsvarighet i arkivbeskrivning
Roll/Ytterligare information → arkivbeskrivningens roll i samband med metadata eller annan ytterligare information. Till exempel CaseFile.Title exporteras alltid som titeln på materialet i rollen ”Huvudtitel”, Record.NativeId alltid i rollen ”Annan beteckning”.
Om Record-nivån för sahke.xml innehåller flera Document-element som alla har samma UseType (till exempel ”Arkiv”), skapas också en egen underenhet med namnet ”Fil X" under underenheten Record för varje Document-element.
Informationen om de här underenheterna är inte listade i tabellen nedan. Document-elementet innehåller inte i sig någon information som beskriver objektet, så informationen i underenheten som ska skapas kopieras från Record-elementet på nivån över den.
sahke.xml-element på högsta nivå | sahke.xml-element | Ruta för metadatalager | Roll/Ytterligare information |
Metadata | CaseFile | AI05 – Nivå | Arkivenhet |
CaseFile | Title | AI02 – Titel | Huvudtitel |
CaseFile | Created | AI03 – Tid | Tidsmässig omfattning, starttid |
CaseFile | Finished | AI03 – Tid | Tidsmässig täckning, slutdatum |
TransferInformation | NativeId | AI01 – Beteckning | TransferOID |
CaseFile | NativeId | AI01 – Beteckning | Annan beteckning |
CaseFile | OtherId | AI01 – Beteckning | Antingen Diarienummer eller Annan beteckning kan väljas |
CaseFile | Subject | AI16 – Datainnehåll | – |
CaseFile | Abstract | AI16 – Datainnehåll | – |
CaseFile | Description | AI16 – Datainnehåll | – |
CaseFile | Custom | AI16 – Datainnehåll | – |
Action | Record | AI05 – Nivå | Underenhet |
Record | Title | AI02 – Titel | Huvudtitel |
Record | Created | AI03 – Tid | Tidsmässig omfattning, starttid |
Record | Accepted | AI03 – Tid | Tidsmässig täckning, slutdatum |
Record | NativeId | AI01 – Beteckning | Annan beteckning |
Record | OtherId | AI01 – Beteckning | Antingen Diarienummer eller Annan beteckning kan väljas |
Record | Subject | AI16 – Datainnehåll | – |
Record | Abstract | AI16 – Datainnehåll | – |
Record | Description | AI16 – Datainnehåll | – |
Record | Custom | AI16 – Datainnehåll | – |
Record | SignatureDescription | AI10 Materialets historia | – |
Record.Restriction | PublicityClass | AI68 – Offentlighetsklass | – |
Record.Restriction | SecurityReason | AI23 – Användningsbegränsning | – |
Record.Restriction | SecurityClass | AI69 – Säkerhetsklass | – |
Record.Restriction | ProtectionLevel | AI65 – Skyddsnivå | Upphört 1.1.2020 |
Metadata | CaseFile | AI05 – Nivå | Underenhet → enskild CaseFile som brutits från sahke.xml, distributionsexemplar .xml-fil |
– | – | AI02 – Titel | Huvudtitel: ”S2-dokument” |
CaseFile | Created | AI03 – Tid | Tidsmässig omfattning, starttid |
CaseFile | Finished | AI03 – Tid | Tidsmässig täckning, slutdatum |
CaseFile | NativeId | AI01 – Beteckning | Annan beteckning |
CaseFile | OtherId | AI01 – Beteckning | Diarienummer eller Annan beteckning |
CaseFile | Subject | AI16 – Datainnehåll | – |
CaseFile | Abstract | AI16 – Datainnehåll | – |
CaseFile | Description | AI16 – Datainnehåll | – |
CaseFile | Custom | AI16 – Datainnehåll | – |
CaseFile.Restriction | PublicityClass | AI68 – Offentlighetsklass | – |
CaseFile.Restriction | SecurityReason | AI23 – Användningsbegränsning | – |
CaseFile.Restriction | SecurityClass | AI69 – Säkerhetsklass | – |
CaseFile.Restriction | ProtectionLevel | AI65 – Skyddsnivå | Upphörde att gälla 1.1.2020, kan fortfarande förekomma i material eller dokument som skapats före början av 2020. |
Överföring av kontextmetadata

En förutsättning för överföring av överföringspaket är att den beskrivande kontextmetadatan har producerats i Riksarkivets metadatasystem.
Som framgår av figuren ovan är överföring av kontextmetadata via gränssnittet endast obligatorisk när överföringspaketet som ska överföras i Sähke2-överföringsstrukturen. Det här beror på att Sähke2-överföringsstrukturen innehåller både kontextmetadata och själva filerna. I andra överföringsstrukturer kan överföringen ske stegvis genom att man först genererar beskrivande kontextmetadata antingen via gränssnittet (metadata måste normaliseras med hjälp av metadatakatalogen) eller via Sapas överföringsgränssnitt på https://ka-sapa.arkisto.fi eller https://sapa.arkisto.fi (Statsförvaltningen).
Observera att för att överföra kontextmetadata via gränssnittet krävs en Api-nyckel som hämtas från Sapas användargränssnitt. Mer information om hur du hämtar och använder Api-nyckeln på sidan finns i avsnittet Hämta Api-nycklar.
Tabellen nedan visar hur informationsmaterial med kontextmetadata kan överföras till Riksarkivet i olika överföringsstrukturer när överföringsgränssnittet används för överföringen av överföringspaketet.
Överföringsstruktur | Överföringssätt för kontextmetadata | Överföringssätt för överföringspaket |
Sähke2 -material | Gränssnitt | Gränssnitt |
Digitaliserat bildmaterial | Gränssnitt/Grafiskt användargränssnitt | Gränssnitt |
Strukturerat informationsmaterial | Gränssnitt/Grafiskt användargränssnitt | Gränssnitt |
Övrigt digitaliserat informationsmaterial | Gränssnitt/Grafiskt användargränssnitt | Gränssnitt |
Beteckning som möjliggör överföring

Beteckningen krävs redan för att skapa kontextmetadata, om inte bara överföringspaketen laddas ner utan metadata även skapas via gränssnittet.
Beteckningen som möjliggör överföring är TransferOID som börjar med ”urn:oid:” och som ges av Sapa. Beteckningen är densamma som beteckningen som användes för att skapa kontextmetadata. I samband med TUS-rubriker i överföringspaket är det obligatoriskt att använda dem för att binda överföringspaketen till rätt helhet som överförs.
Hämta Api-nycklar

Api-nycklarna hämtas i överföringsgränssnittet. Förutsättningen för att hämta en Api-nyckel är att du har tilldelats rätt roll i överföringsgränssnittet av Riksarkivet i den administrativa fasen.
Användning av Api-nyckel på överförarens anslutningsserver
Den Api-nyckel som skapats ovan behövs när anrop görs från anslutningsservern till Sapas gränssnitt. Förutom platsen och metoden för Sapa-plattformens gränssnittsendpoints måste varje gränssnittsanropan tillhandahålla följande allmänna information:
Verifiering:
Kundcertifikat för anslutningsprogrammet X-Road, PEM-format
X-Road certifieringsnyckel, PEM-format
Header:
Beteckning för kundsubsystemet X-Road (CLIENT-SUBSYSTEM), Client ID för det subsystem som skickar begäran
Api-nyckel som skapats av kunden i Sapa
Den grundläggande strukturen för en begäran från en anslutningsserver till en annan med curl-programmet är följande:
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>"
Adressen till gränssnittsbegäran, avsnittet efter ”-X POST” i föregående exempel, består av följande information:
Riksarkivets anslutningsserver (XROAD-SERVER):
https://ka-palveluvayla.kansallisarkisto.fi/r1/Subsystemet (TARGET-SUBSYSTEM) som begäran riktar sig till:
FI/GOV/0245885-9/sapa/wsObjekt i REST-gränssnittet, till exempel
/api/latest/statuses/document_id
Beskrivning av REST-gränssnittet
Den aktuella REST-API-beskrivningen i OpenAPI-format finns i Suomi.fi-anslutningskatalogen
Test: Tjänsten för digital arkivering - ws - Informationsledens testmiljö
Produktion: Tjänsten för digital arkivering - ws - Informationsleden
Spara kontextmetadata i en överföringspost → POST /api/latest/context-metadata
Kontextmetadata ges i meddelandet som formulärinformation (multipart/form-data). Ett korrekt svar kommer att visa kontextmetadatan som sparats i sin helhet, inklusive dess specificerande beteckning i Sapa.
Förutom rutorna som anges nedan finns det även andra rutor i ett korrekt returmeddelande. Sapa fyller i dem automatiskt vartefter kontextmetadata bearbetas, så ingenting lagras i dem i samband med att raden skapas. Till exempel i rutan ”accepted_at” lagras tidsstämpeln för när kontextmetadata har överförts fullständigt och lagrats i metadatalagret för arkivbeskrivning; ”ahaa_content_id” → den tekniska beteckning som tilldelats raden i metadatalagret. Dessutom används ”parent_context_metadata_id” och rutorna som börjar med ”identifier_sahke” och ”sahke” endast och uteslutande för att hantera Sähke2-överföringen och fylls automatiskt i av Sapa i bakgrunden baserat på innehållet i Sähke2-paketet.
De rutor som är markerade som obligatoriska nedan måste ingå i meddelandet för att kontextmetadata överhuvudtaget ska kunna överföras till metadatalagret i nästa steg.
Om till exempel ”parent_id” eller ”ahaa_series_id” saknas i meddelandet lagras kontextmetadataraden ändå fullständigt i Sapas backend-bas, men slutförandet av informationen stoppas av felet HTTP 400 – Bad Request.
Informationen kan inte ändras efter att den sänts, så kontrollera formatet noggrant.
Bestämningar för meddelandet
Element | Nödvändighet | Beskrivning |
transfer_oid | Obligatoriskt | Beteckning för överföringsposten som getts av Sapa, TransferOID i formatet ”urn:oid:1.2.246.58.200.nnn...”. |
transfer_set_id | Obligatoriskt | Specificerande beteckning för överföringsposten som getts av Sapa, format UUID. |
parent_id | Obligatoriskt | Teknisk beteckning för metadatalagret för arkivbeskrivning som getts av Sapa, och som överföringspaketet och kontextmetadata är kopplade till. Värdet får inte lämnas tomt och måste vara detsamma som ”ahaa_series_id”. |
ahaa_series_id | Obligatoriskt | Värdet får inte lämnas tomt och måste vara detsamma som ”parent_id”. |
metadata | Obligatoriskt | Mer information om innehållet i och skapandet av elementet finns på Bruksanvisning för och beskrivning av Metadatakatalogen och Exempel på metadata för överföring. Kontextmetadata som beskriver överföringspaketet i JSON-format. Värdet på ”metadata”-elementet ska representeras i strängformat så att nyckel-värdeparen som det innehåller bildar ett giltigt JSON-dokument. |
status | Obligatoriskt | Anger status för kontextmetadataraden som beskriver överföringspaketet som skapas. Värdet måste alltid vara ”approved”. |
include_in_transfer | Obligatoriskt | Ett booleskt värde som anger om metadataraden som skapats ska inkluderas i överföringsposten. Värdet måste alltid vara ”true”. |
local_transfer_id | Obligatoriskt | Namnet på överföringspaketet som är kopplat till metadataraden i källsystemet utan filtyp. Värdet får inte lämnas tomt. |
order | Alternativ | Heltal, ordningsnummer för metadataraden. Informationen överförs och är senare tillgänglig både i metadatalagret för arkivbeskrivning och i Astia i den ordning som informationen lagras. Värdet är inte obligatoriskt men det rekommenderas att använda löpande numrering, särskilt om det finns många objekt som ska beskrivas, till exempel ett stort antal överföringspaket. |
Returmeddelande i normala situationer
HTTP 200 OK – Meddelandet lyckades, tillagd kontextmetadata i JSON-format returneras.
HTTP 400 Bad Request – Meddelandet stöder inte parametrarna.
HTTP 403 Forbidden – Åtkomst nekad, användaren har inte behörighet att komma åt den här resursen.
HTTP 405 Method Not Allowed – Fel metod används i meddelandet (annan än POST).
HTTP 409 Correct – Det finns redan metadata med samma materialbeteckning för arkivmetadatasystemet, den lokala specificerande beteckningen för överföringspaketet används redan i samma överföringspost, eller materialet har redan digitala uttryck i arkivmetadatasystemet.
Textstomme för ett korrekt returmeddelande
Avsnittet ”metadata” i returmeddelandet nedan innehåller exempelvärden som är avsedda att beskriva obligatoriska metadata. Värdena i ett korrekt returmeddelande är inte nödvändigtvis desamma.
{
"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"
}
Slutföra kontextmetadata → POST /api/latest/transfer-set/document_id/finalize
När all kontextmetadata för överföringspaketen i överföringsposten har skapats och lagrats i Sapas backend-bas måste kontextmetadata fortfarande överföras till Riksarkivets metadatalager för arkivbeskrivning Det här görs med POST-metoden på endpointen /api/latest/transfer-set/{document_id}/finalize.
Svarsmeddelandet på en korrekt begäran innehåller de specificerande beteckningarna för kontextmetadataraderna och motsvarande tekniska beteckningar för metadatalagret för arkivbeskrivning.
Alla kontextmetadatarader i överföringsposten måste ha minst den obligatoriska metadata och radstatusen ”approved”.
Bestämningar för meddelandet
Parameter | Nödvändighet | Beskrivning |
document_id | Obligatoriskt | Den specificerande beteckningen ”transfer_set_id” inom Sapa som Sapa ger överföringsposten. |
Returmeddelande i normala situationer
HTTP 200 OK – Meddelandet lyckades, svaret ges som en JSON-lista med de specificerande beteckningarna för överföringspaketen sammankopplade med motsvarande tekniska beteckningar i metadatalagret för arkivbeskrivning.
HTTP 400 Bad Request – Meddelandet stöder inte parametrarna.
HTTP 404 Not found – Inga överföringsposter hittades med beteckningen för överföringsposten eller beteckningen var felaktig.
HTTP 405 Method Not Allowed – Fel metod används i meddelandet (annan än POST).
HTTP 409 Conflict – Kontextmetadataraden har annan status än ”approved” eller saknar obligatorisk information (till exempel är informationen om materialets ägare, owner_organization, tom).
Textstomme för ett korrekt returmeddelande
{
"data": {
"identifiers": [
{
"ahaa_id": "AHAA id1",
"local_id": "local id1"
},
{
"ahaa_id": "AHAA id2",
"local_id": "local id2"
}
]
},
"status": "success"
}
Överföring av överföringspaket

Ett TUS-protokoll används för att ladda ner överföringspaketen, https://tus.io. Protokollet kräver en separat TUS-client som fungerar i X-Road-miljön i Informationsleden.
Mer information finns på https://github.com/Sapa-Kansallisarkisto/xroad-tus-py-client
Överföringspaketen laddas ner för att behandlas i Sapa via gränssnittet på följande sätt:
Utrymme reserveras för överföringspaketet i Sapa, det vill säga sändningen inleds.
POST /api/latest/uploads → i svarsheadern finns resource_id som identifierar resursen i överföringspaketet.Överföringspaketet sänds i delar med hjälp av TUS-protokollet, med beteckningen som gavs tidigare.
PATCH /api/latest/uploads/resource_idMellan Patch-begärandena kan man fråga om hur filhämtningen fortskrider med Head-metoden från samma endpoint som i föregående avsnitt. Svarsrubrikerna innehåller information om storleken på överföringen i Sapa-plattformen, som till exempel kan användas för att beräkna hur stor andel av sändningen som har slutförts.
HEAD /api/latest/uploads/resource_idNär överföringspaketet har sänts i sin helhet måste sändningen fortfarande slutföras, och då inleds processningen i Sapa.
POST/api/latest/transfers/resource_id → i svarstexten finns den specificerande beteckningen id för att behandla överföringsposten, som senare i instruktionerna visas som document_id.I endpoint kan du fråga om statusen för behandlingen av överföringspaketet i Sapa.
GET/api/latest/statuses/document_id → det relevanta i svarsstommen är data.status, som innehåller statusen för eller resultatet av behandlingen. Eventuella värden listas nedan under den mer detaljerade beskrivningen för endpoint.
Sapa utför flera kontroller av både strukturen och filerna i överföringspaketet och om paketet klarar alla kontroller skickas SIP-versionen (Submission Information Package) till systemet Kulturarv-LDB. När Kulturarv-LDB har behandlat överföringspaketet sänds informationen – accepterad eller avvisad – tillbaka till Sapa och behandlingen av paketet avslutas.
Initiera sändning, POST /api/latest/uploads
Rubriken för meddelandet måste innehålla tekniska metadata som beskriver den fil som ska skickas, bland annat filens namn och typ av överföringsstruktur. En beskrivning av strukturen för Upload-Metadata och exempel finns i slutet av den här sidan under ”Exempel på Upload-Metadata”.
Upload-Metadata måste vara i exakt det format som beskrivs nedan. Till exempel får inte flera mellanslag användas i informationen för att skilja nyckeln och dess värde åt.
Bestämningar för meddelandet
Meddelandet innehåller endast information i rubriken för begäran. Returmeddelandet innehåller också bara information i rubriken. I rubriken för begäran måste följande information anges i form av nyckel-värdepar:
Tus-Resumable – Version av TUS-protokollet, alltid ”1.0.0”
Upload-Length – Filstorlek för uppladdningspaketet i byte
Upload-Metadata – Metadata för sändningen
Metadata för sändningen anges som nyckel-värdepar, så attnamnet på nyckeln är plain-text,
värdet presenteras i Base64-kodad form,
nyckeln och värdet är åtskilda med ett mellanslag, och
paren separeras med ett kommatecken (,).
Returmeddelande i normala situationer
HTTP 201 Created – Initieringen lyckades. Returmeddelandet innehåller bara rubrik, ingen textstomme. I rubriken anges adressen som du kan börja skicka filen till.
HTTP 400 Bad Request – De angivna metadata är inte giltig eller den angivna filstorleken är 0.
HTTP 403 Forbidden – Åtkomst nekad, användaren har inte behörighet att komma åt den här resursen.
HTTP 405 Method Not Allowed – Fel metod i meddelandet (annan än POST eller OPTIONS).
HTTP 412 Precondition Failed – Den angivna versionen av TUS-protokollet stöds inte.
HTTP 503 Service Unavailable – Sapa kan inte ta emot sändningen.
Information om rubriken i ett korrekt returmeddelande
Location – URL, beteckningen för resursen som själva överföringspaketet kan skickas till
Tus-Resumable – Versioner av TUS-protokollet som stöds av Sapa
Location-svaret har formen https://sapa.arkisto.fi/api/latest/uploads/{resource_id} eller https://ka-sapa.arkisto.fi/api/latest/uploads/{resource_id}. Resource_id måste plockas ut från slutet av URL:en, eftersom endast resource_id (inte hela URL:en) ska finnas i headern när filen sänds.
Sända en fil, PATCH /api/latest/uploads/resource_id
När sändningen av filen har initierats korrekt kan överföringspaketet börja skickas till Sapa-plattformen. Sändningen sker med hjälp av TUS-protokollet, som delar upp filen som ska skickas i bitar (1 MB som standard) och skickar dem i en kö till det mottagande systemet. Användningen av TUS-protokollet gör att filen kan fortsätta att laddas ner om anslutningen mellan det överförande och mottagande systemet oväntat skulle brytas.
Bestämningar för meddelandet
resource_id – Beteckning för resursen som genereras av TUS-protokollet. Den adress som anges i rubriken för returmeddelandet för initiering av sändning, under nyckeln Location.
I textstommen för meddelandet anges överföringspaketet i delar av typen application/octet-stream.
Dessutom måste följande information anges i rubrikerna för begäran:
Tus-Resumable – Version av TUS-protokollet.
Upload-Offset – Avståndet i byte från början av paketet till den del som ska skickas i meddelandestommen. Det här anger var i filen den del som sänts hör hemma. Om sändningen avbryts gör det här värdet att sändningen kan återupptas där den slutade.
Returmeddelande i normala situationer
HTTP 204 No Content – Sändningen lyckades, en del av överföringspaketet sändes korrekt.
HTTP 400 Bad Request – Storleken på delen som angavs är 0.
HTTP 403 Forbidden – Åtkomst nekad, användaren har inte behörighet att komma åt den här resursen.
HTTP 404 Not Found – Den angivna resursen hittades inte.
HTTP 405 Method Not Allowed – Fel metod i meddelandet (annan än PATCH eller HEAD).
HTTP 409 Conflict – Den angivna informationen för Upload-Offset är inte giltig.
HTTP 412 Precondition Failed – Den angivna versionen av TUS-protokollet stöds inte.
HTTP 415 Unsupported Media Type – Formatet på datan som skickas i textstommen stöds inte.
Information om rubriken i ett korrekt returmeddelande
Upload-Offset – Totalt antal byte för de sända delarna, den nuvarande storleken på överföringspaketet i Sapa.
Tus-Resumable – Versioner av TUS-protokollet som stöds av Sapa
När Upload-Offset stämmer överens med filstorleken på överföringspaketet som angavs när sändningen initierades, är sändningen slutförd och hela överföringspaketet har överförts till Sapa. Sändningen måste sedan slutföras för att Sapa ska kunna behandla överföringspaketet.
Fråga om status för en sändning, HEAD /api/latest/uploads/resource_id
Efter initialisering av sändningen och mellan sändningen av delarna i överföringspaketet kan statusen för sändningen efterfrågas här. Rubriken för svaret innehåller bland annat information om hur stor del av överföringspaketet som redan har tagits emot. Den informationen kan till exempel användas för att beräkna hur stor andel av sändningen som har slutförts. Parametern resource_id är densamma som beteckningen som behövs för att sända paketet ovan.
Bestämningar för meddelandet
resource_id – Beteckning för resursen som genereras av TUS-protokollet. Den adress som anges i rubriken för returmeddelandet för initiering av sändning, under nyckeln Location.
Textstommen i meddelandet är tom. Följande information måste anges i rubrikerna för begäran:
Tus-Resumable – Version av TUS-protokollet.
Returmeddelande i normala situationer
HTTP 200 Ok – Förfrågan lyckades.
HTTP 403 Forbidden – Åtkomst nekad, användaren har inte behörighet att komma åt den här resursen.
HTTP 404 Not Found – Den angivna resursen hittades inte.
HTTP 405 Method Not Allowed – Fel metod i meddelandet (annan än PATCH eller HEAD).
HTTP 412 Precondition Failed – Den angivna versionen av TUS-protokollet stöds inte.
Information om rubriken i ett korrekt returmeddelande
Cache-Control – Information om hur cacheminnet ska hanteras, värdet är alltid ”no-store”.
Upload-Offset – Totalt antal byte för de sända delarna, den nuvarande storleken på överföringspaketet i Sapa.
Tus-Resumable – Versioner av TUS-protokollet som stöds av Sapa
Upload-Metadata – Metadata som anges vid initieringen
Upload-Length – Storleken på sändningen i byte, anges vid initieringen
Slutföra sändning, POST /api/latest/transfers/resource_id
När överföringspaketet har sänts till Sapa i sin helhet måste överföringen fortfarande slutföras innan processningen i Sapa startar. Returmeddelandet innehåller den specificerande beteckningen för sändningen i arbetsflödet i Sapa (document_id), vilket är samma som det resource_id som användes ovan.
Bestämningar för meddelandet
resource_id – Beteckning för resursen som genereras av TUS-protokollet. Den adress som anges i rubriken för returmeddelandet för initiering av sändning, under nyckeln Location.
Returmeddelande i normala situationer
HTTP 200 OK – Meddelandet lyckades, meddelandets textstomme innehåller den beteckning för överföringspaketet som genererats av Sapa.
HTTP 403 Forbidden – Åtkomst nekad, användaren har inte behörighet att komma åt den här resursen.
HTTP 404 Not Found – Den angivna resursen hittades inte.
HTTP 405 Method Not Allowed – Fel metod används i meddelandet (annan än POST).
HTTP 409 Conflict – Resursen är ännu inte klar, överföringspaketet har inte ännu överförts helt och hållet.
Textstomme för ett korrekt returmeddelande
{
"data": {
"object": {
"id": "Unique document ID",
}
},
"status": "success"
}
id är den specificerande beteckningen för överföringspaketet som genereras av Sapa. Identifieraren används för att hämta information om paketet i statusförfrågningar.
Förfrågan om status för behandlingen av ett överföringspaket, GET /api/latest/statuses/document_id
När överföringspaketet har laddats upp till Sapa-plattformen i sin helhet och sändningen har slutförts, påbörjas processningen i Sapa. Du kan fråga om status och hur behandlingen fortskrider i den här endpointen.
Bestämningar för meddelandet
document_id – Specificerande beteckning för överföringspaketet i Sapa.
Returmeddelande i normala situationer
HTTP 200 OK – Meddelandet lyckades, informationen i överföringspaketet som hittats returneras i JSON-format.
HTTP 400 Bad Request – Meddelandet stöder inte parametrarna.
HTTP 403 Forbidden – Åtkomst nekad, användaren har inte behörighet att komma åt den här resursen.
HTTP 404 Not Found – Paketet hittades inte.
HTTP 405 Method Not Allowed – Fel metod används i meddelandet (annan än GET).
Textstomme för ett korrekt returmeddelande
{
"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"
}
Resultatelementet innehåller samma information som sök- och listningsinformationen i överföringspaketet. Dessutom visas följande information:
aip_id – Beteckning för ett paket som ska långtidsförvaras i PAS.
filename – Paketets filnamn.
mets_objid – Beteckning i PAS för överföringspaketet som skapats.
package_type – Pakettyp för överföringspaketet.
tasks – Steg i arbetsflödet. Tasks innehåller information om alla steg som utförs, tidsstämplar för dem och beskrivningar av resultaten för stegen:
result – Anger om steget slutfördes korrekt eller inte; värdet kan vara antingen ”success” eller ”failure”.
timestamp – Tidsstämpel för när steget utförts.
messages – Beskrivning av resultatet för tidsstämpel.
Ahaa-ids listar den tekniska beteckningen för varje metadatalager för arkivbeskrivning som är associerat med innehållet i paketet:
level – Nivå på materialet, ”volume” = Arkivenhet, ”sub-volume” = Underenhet
value – Teknisk identifierare för metadataarkivet
Om paketet avvisas, innehåller resultatelementet följande information:
failure – Felmeddelande för avvisade paket.
Exempel på Upload-Metadata
Informationen om överföringspaketet ska anges som en del av initieringen i samband med att överföringspaketet sänds.
POST /api/latest/uploads-gränssnittsanropan. Vilken ordning informationen presenteras i har ingen betydelse, men följande regler måste följas:
Nyckelns värde måste vara kodat med Base64.
Nyckel och värde åtskiljs med ett mellanslag, nyckel-värdepar åtskiljs med ett kommatecken utan andra tecken. I exemplen nedan har radbrytningar använts för göra det mer läsbart.
Dessutom måste MD5-kontrollsumman för överföringspaketet vara i gemener före Base64-kodning.
Nödvändiga uppgifter:
filename → namn på överföringspaketet, inklusive filtyp
package_checksum → MD5-kontrollsumma för överföringspaketet
package_type → namn på överföringsstrukturen i Sapa
transfer_oid → beteckning för överföringsposten som börjar med ”urn:oid:”
Endast för Sähke2-material:
ahaa_series_id → den tekniska beteckningen på högsta nivå som tilldelats av Sapa och som överföringspaketet är kopplat till
Dessutom för digitaliserad bilddata:
digitization_rationale → Riksarkivets kvalitetskriterier
Digitaliserat bildmaterial | |
Upload-Metadatavärden för TUS-sändning
CODE
| Förklaring av värden
CODE
|
Övrigt digitaliserat informationsmaterial | |
Upload-Metadatavärden för TUS-sändning
CODE
| Förklaring av värden
CODE
|
Strukturerat informationsmaterial | |
Upload-Metadatavärden för TUS-sändning
CODE
| Förklaring av värden
CODE
|
Sähke2 | |
Upload-Metadatavärden för TUS-sändning
CODE
| Förklaring av värden
CODE
|