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:

1. Ett XML-kommentarblock (<!-- -->), omedelbart efter XML-deklarationen, som anger vad som är relevant för hela överföringsposten i den struktur som beskrivs nedan.

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

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

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

• Objekt 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

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

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:

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

2. Överföringspaketet sänds i delar med hjälp av TUS-protokollet, med beteckningen som gavs tidigare.
   PATCH /api/latest/uploads/resource_id

3. Mellan 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_id

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

5. 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å att

  • namnet 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

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

Egenskapen              | Värde som valnig text
------------------------|---------------------------------------
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

Egenskapen              | Värde som valnig text
------------------------|---------------------------------------
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

Egenskapen              | Värde som valnig text
------------------------|---------------------------------------
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

Egenskapen              | Värde som valnig text
------------------------|---------------------------------------
ahaa_series_id          | 1234567890
filename                | 1234567890.tar
package_checksum        | 08f43d271d9bbf67a2f02bd8079a2046
package_type            | sahke2
transfer_oid            | urn:oid:1.2.246.582.200.134985728679348093805279867