UiBhjelps åpne kunnskaps­kort

KI 3742 Ny funksjon: dataoverføring via SAFE File API

(oppdatert )
Oversikt av hva SAFE File API er, og import og eksport av data for SAFE servere ved bruk av den.
Hva er SAFE File API?

SAFE File API er et REST-basert grensesnitt som sitter mellom SAFE serveren og din lokale maskin. Ved bruk av et eksternt verktøy vil du kunne kommunisere mot API'ets endepunkter og overføre data inn og ut av SAFE serveren. Denne løsningen korter tiden for dataoverføring ned betraktelig sammenlignet med tidligere løsning. Samtidig er begge dataoverføringsmetoder fortsatt tilgjengelig i en god stund fremover.

Det er viktig å vite at SAFE File API ikke er et verktøy i seg selv, men en måte å kommunisere med SAFE serverne på. Nedenfor forklarer vi nærmere bruk av verktøy og hvordan man bruker API'et for import/eksport av data.

Krav for å bruke SAFE File API
  • Være en eksisterende SAFE bruker med tilgang til import og/eller eksport.
  • Ha tilgang til å bruke SAFE File API spesifikt. Hvis du ikke har tilgang kan du spørre om dette i en forespørsel til UiB Hjelp, sammen med brukernavn og servernavn.
  • Ha tilgang til og være koblet opp mot UiB SAFE VPN. Nærmere beskrivelse av dette forklares her: KI 0407 Oppkobling mot SAFE server
  • Ha et program eller annet verktøy for å kommunisere mot endepunkter definert i SAFE File API. Du kan fritt velge hvilket verktøy du vil bruke selv, men et alternativ vi anbefaler er NORTRE CLI, som vi har laget selv. Her har vi også en guide for hvordan du bruker dette kommandolinje verktøyet for import/eksport: KI 3743 Nytt SAFE verktøy: import/eksport med NORTRE CLI
Generell guide for bruk av SAFE File API

NB: Dette er en generell guide for hvordan man kommuniserer med endepunktene for alle verktøy.
Hvis dette virker vanskelig å forstå, går vi i mer detalj på det anbefalte verktøyet NORTRE CLI her: KI 3743 Nytt SAFE verktøy: import/eksport med NORTRE CLI.
Det kan være lettere å følge steg for steg hvordan man bruker ett verktøy, siden alle verktøy er litt forskjellig i hvordan de fungerer.
I tillegg er NORTRE CLI laget spesifikt med SAFE File API i tankene.

Etter du har koblet opp til SAFE VPN og har kommunikasjonsverktøyet ditt klart, vil du interagere med visse endepunkter.
Hent ut nøkkel (token)

Aller først trenger vi en nøkkel for å vise at vi har rettigheter til å sende forespørsler til de andre endepunktene. Dette endepunktet er blokkert av innlogging på UiB, så du må lime adressen inn i nettleseren først for så å logge inn.

Eksempelbilde av UiB innlogging i nettleser.

Etter autentisering vil du motta en nøkkel (access token) i nettleseren.

Eksempelbilde på vellykket autentisering og nøkkel.

Her er nøkkelen blitt sensorert med en svart boks, men vanligvis vil det være en lang tekst med bokstaver og tall. Denne teksten må du kopiere og legge inn i det valgte verktøyet ditt.

Hvordan dette gjøres er litt forskjellig fra verktøy til verktøy. For noen ser man etter "auth" og "bearer token" der man kan lime det inn i en fast plass, i mens for andre sender man det med i selve forespørselen til de andre endepunktene. Det er anbefalt å lese dokumentasjon på dette (token handling) for det valgte verktøyet ditt.

Viktig: Denne nøkkelen vil kun være gyldig i 1 time. Etter dette må du gjøre dette steget på nytt og få en ny nøkkel igjen.

Importering

Etter du har fått en nøkkel (token) som beskrevet ovenfor, kan du importere filer inn til SAFE serveren fra din lokale PC. Dette gjøres ikke i nettleser som beskrevet ovenfor med å få tak i nøkkel (tokens), men fra det valgte kommunikasjonsverktøyet ditt. Ikke bli forvirret over at endepunktene er klikkbar eller uthevet i blå i resten av artikkelen, dette skjer bare automatisk. Husk også å fortsatt ha UiB SAFE VPN aktivert under prosessen.
  • Generelt endepunkt for importering: POST https://api.safe.uib.no/v1/files/import
Du må i tillegg ha en struktur på forespørselen din, med visse parametre.
  1. Headers
Headers er metadata som er nødvendig for å gjøre en HTTP-forespørsel mot et endepunkt.
For kommunikasjon mot SAFE File API til import-endepunktet krever vi:
  • Content-Type med "multipart/form-data" som verdi.
    Denne settes som oftest automatisk av verktøyet ditt når du sender en forespørsel, så du trenger ikke tenke så mye over det.
  • Authorization med "bearer token" verdi-format. Verdien skal være nøkkelen (token) du fikk i sted.

       2. Body

Body er selve innholdet du sender med forespørselen. I dette tilfellet er det bare selve filen du ønsker å importere.
  • Feltet "file" med filinnholdet som verdi.
For å vise til filen skriver man ofte bare filnavnet med fil-endelsen.
Eksempelvis: "blabla.txt"

I terminalen står du ofte ikke i samme filsti som der filen du ønsker å importere ligger. Da må du spesifisere både filstien og filnavnet.
Eksempelvis: "C:\Users\brukernavn\Documents\blabla.txt"


       3. Query Parameters

Query Parameters (eller spørringer) skrives direkte inn etter endepunktet.
For kommunikasjon mot SAFE File API til import-endepunktet krever vi:
  • Parameteren "filename" av string-verdi (tekst).
    Her spesifiserer vi om filen vi importerer inn skal ha et nytt navn og fil-endelse i SAFE-serveren.
    Vanligvis skriver man bare inn samme filnavn her som man spesifiserte i body.
    Eksempelvis: "filename=blabla.txt".
  • Parameteren "server" av string-verdi (tekst).
    Her spesifiserer du SAFE serveren du ønsker å importere fil/er inn til.
    Eksempelvis: "server=safemaskinnavn"
Eksempel med begge parametre: POST https://api.safe.uib.no/v1/files/import?filename=blabla_nyttnavn.txt&server=safemaskinnavn
  • Fullt generisk eksempel:
```
verktøy  -X POST "https://api.safe.uib.no/v1/files/import?filename=blabla_nyttnavn.txt&server=safemaskinnavn" \
                -H "Authorization: Bearer 12ASXDF3oigyXuyxef123ff3jh4" \
                -F "file=@C:\Users\brukernavn\Documents\blabla.txt"
```

En ekte nøkkel (token) kommer til å være mye lengre enn eksempelet vist over.
Husk igjen også at hvert verktøy har ulike formateringer og variabler.
  • Mer om importering:
Etter importering vil fil/er dukke opp i import-mappen på den valgte SAFE maskinen, altså safe_file_api_import, gitt at du har import-tilgang.

NB: Filene du importerer inn i SAFE serveren er kun tilgjengelig for deg på serveren. Ingen andre har adgang til å se disse før du flytter dem inn på et felles område. Importering vil feile om filen ikke blir funnet eller om filen er tom. Du vil også få feilmelding om filnavnet allerede eksisterer på SAFE serveren i import-mappen.

Eksportering

Samme som for importering, etter du har fått tak i en nøkkel (token), kan du eksportere filer fra SAFE maskinen til din lokale PC. Ikke bli forvirret over at endepunktene er klikkbar eller uthevet i blå i resten av artikkelen, dette skjer bare automatisk. Husk også å fortsatt ha UiB SAFE VPN aktivert under prosessen.
  • Generelt endepunkt for eksportering: GET https://api.safe.uib.no/v1/files/export

Du må i tillegg ha en struktur på forespørselen din, med disse parametrene:
  1. Headers
Headers er metadata som er nødvendig for å gjøre en HTTP-forespørsel mot et endepunkt.
For kommunikasjon mot SAFE File API til eksport-endepunktet krever vi:
  • Authorization med "bearer token" verdi-format. Verdien skal være nøkkelen (token) du fikk i sted.

      2. Query Parameters

Query Parameters (eller spørringer) skrives direkte inn etter endepunktet.
For kommunikasjon mot SAFE File API til eksport-endepunktet krever vi:
  • Parameteren "filename" av string-verdi (tekst).
    Her spesifiserer vi hvilken fil som skal eksporteres ut fra SAFE-serveren.
    Husk at filen må være plassert i mappen safe_file_api_export først.
    Eksempelvis: "filename=blabla.txt".
  • Parameteren "server" av string-verdi (tekst).
    Her spesifiserer du SAFE serveren du ønsker å eksportere fil/er ut av.
    Eksempelvis: "server=safemaskinnavn".
Eksempel med begge parametre: GET https://api.safe.uib.no/v1/files/export?filename=blabla.txt&server=safemaskinnavn
  • Fullt generisk eksempel:
```
verktøy  -X GET "https://api.safe.uib.no/v1/files/export?filename=blabla.txt&server=safemaskinnavn" \
                -H "Authorization: Bearer 12ASXDF3oigyXuyxef123ff3jh4" \
                -o "C:\Users\brukernavn\Downloads\blabla.txt"
```

Vi har tatt med en ekstra parameter her ( -o ), for å demonstrere at verktøyet du bruker kan ha en funksjon for å lagre filen et spesifikt sted på PC'en din, framfor bare å hente innholdet direkte.
En ekte nøkkel (token) kommer til å være mye lengre enn eksempelet vist over.
Husk igjen også at hvert verktøy har ulike formateringer og variabler.
  • Mer om eksportering:
Husk at filen må være plassert i mappen safe_file_api_export på serveren før du eksporterer. Etter eksportering vil innholdet til filen dukke opp i verktøyet på din lokale maskin. Lagring av filen til en spesifikk mappe på PC'en din kommer litt an på hvordan verktøyet opererer. Body er ikke nødvendig å definere ved eksportering siden vi ikke sender inn noe data.

Annen informasjon
  • Selv om nøkkel (token) bare varer 1 time, vil ikke filoverføringer kanselleres om du allerede har startet dataoverføringen. Det gjelder kun for nye forespørsler.
  • Du kan importere og eksportere filer opp til 950 GB, men vær obs på at jo større filene er, jo lengre tid tar det å importere/eksportere dem.
  • Det er timeout på 1 dag, noe som betyr at hvis det tar lengre enn 24 timer å overføre filene, så vil det bli kansellert.
Gi beskjed hvis du opplever problemer eller tenker dette dokumentet bør oppdateres.