UiBhjelps åpne kunnskaps­kort

KI 3743 Nytt SAFE verktøy: import/eksport med NORTRE CLI

(oppdatert )
Oversikt over hva NORTRE CLI er og hvordan man bruker verktøyet.
Hva er NORTRE CLI?

NORTRE CLI er et spesialisert kommandolinjeverktøy laget av SAFE på UiB for import/eksport av filer gjennom SAFE serverene. Verktøyet interagerer med SAFE File API: KI 3742 Ny funksjon: dataoverføring via SAFE File API. Pakken er publisert på Python Package Index (PyPi) under navnet nortre-cli.

Krav for å bruke NORTRE CLI
  • 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
  • En terminal der du kan taste inn kommandoene. Alle operativsystemer kommer med sin standard versjon av dette. Eksempelvis "Powershell" for Windows eller "Terminal" for Mac, samt mange andre.
  • Python må være installert på datamaskinen din. Gjør dette for operativsystemet ditt ved å laste ned fra Python sitt offisielle nettsted.

Guide for bruk av NORTRE CLI

Instruksjonsmanual for de ulike kommandoene er publisert på nettsiden for PyPi-pakken, men vi går i gjennom dem her også.
Installasjon

Åpne en terminal på datamaskinen din. Dobbeltsjekk gjerne at Python ble riktig installert før du fortsetter.
Vi installerer NORTRE CLI-verktøyet fra Python Package Index (PyPi). Skriv inn: pip install nortre-cli
Etter dette bør det komme en installasjon opp en installasjonsprosess som laster ned pakken.

For å teste at installasjon ble vellykket, skriv inn safe-cli i terminalen. Det bør vise en meny med ulike valg.

Eksempelbilde på menyvalg i NORTRE-CLI når du skriver inn safe-cli i valgt terminal.

Hent ut nøkkel (token)

Aller først trenger vi en nøkkel for å vise at vi har rettigheter til å tilgang til å sende forespørsler.

Skriv inn safe-cli get-token i terminalen. Dette skal automatisk åpne nettleseren din, og du vil bli bedt om autentisering.

Eksempelbilde av UiB innlogging i nettleser.

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

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 trykke enter-tasten for å legge inn i NORTE-CLI.
Terminalen vil vente på at du gjør dette med meldingen "Paste your JWT token here: ...".

Eksempelbilde på NORTRE-CLI som venter på at du limer inn nøkkel (token).

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 med kommandoene vist nedenfor. Husk å fortsatt ha UiB SAFE VPN aktivert under prosessen.
  • Interaktiv importering:

Skriv inn safe-cli import-file for å kjøre en interaktiv versjon for importering. Du kan også kjøre safe-cli interactive, for så å velge import alternativet.

Deretter vil du bli spurt om servernavn som du skriver direkte inn i terminalen. En filutforsker vil automatisk åpne seg og du kan velge fil/er du vil importere inn i SAFE maskinen. Etterpå blir du presentert med en oversikt av importeringene før du godkjenner prosessen. Du vil også bli vist en oppsummering av hvilke filer som ble overført og ikke.

Eksempelbilde ved bruk av kommandoen "safe-cli import-file".

Etter godkjenning ved å skrive inn "yes", vil prosessen med importering starte. Prosessen kan ta litt tid basert på filstørrelser. Du vil få tilbakemelding på hvilke filer som ble importert og eventuelle feilmeldinger.

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.
  • Ikke-interaktiv importering:
Det finnes også et alternativ for en ikke-interaktiv måte å importere fil/er på inn i SAFE maskinen, noe som vil starte prosessen med importering umiddelbart.

Da skriver du hele kommandoen på en linje: safe-cli import-file --server <servername> --filename <file-path>
Fullt eksempel med flere import filer: safe-cli import-file --server serverenmin --filename "C:\Users\brukernavnetmitt\Documents\blabla.txt" --filename "C:\Users\brukernavnetmitt\Documents\Hi.txt"

Eksempelbilde ved bruk av ikke-interaktiv eksportering.

Dette vil fungere så lenge du fyller inn servernavn og filstien riktig.
Filstien er litt annerledes på ulike operativsystem (Windows format ovenfor), men det skal fungere for ulike formatteringer helt fint.
Husk også fortsatt å ha gyldig token og SAFE VPN aktivert, ellers vil det feile.
  • Mer om importering:
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 maskinen i import-mappen.

Eksportering

Samme som for importering, etter du har fått en nøkkel (token), kan du eksportere filer inn til SAFE maskinen fra din lokale PC med kommandoene som er spesifisert i verktøyet. Husk å fortsatt ha UiB SAFE VPN aktivert under prosessen.

Eksporteringsprosessen forutsetter at du har lagt filene du ønsker å hente ut inn i safe_file_api_export mappen på SAFE maskinen din.
  • Interaktiv eksportering:

Skriv inn safe-cli export-file for å kjøre en interaktiv versjon for eksportering. Du kan også kjøre safe-cli interactive, for så å velge eksport alternativet.

Du vil bli spurt om servernavn som du skriver direkte inn i terminalen. Når den er validert vil du få en oversikt over hvilke filer som ligger i mappen på SAFE maskinen. Deretter skriver du inn filnavn eller nummeret som samsvarer med filen du ønsker å hente ut. En filutforsker vil åpne automatisk hvor du kan velge hvor filen skal eksporteres på din lokale maskin. Etterpå blir du presentert med en oppsummering av eksporteringen før du godkjenner prosessen.

Eksempelbilde ved bruk av kommandoen "safe-cli export-file".

Etter godkjenning ved å skrive inn "yes", vil prosessen med eksportering starte. Prosessen kan ta litt tid basert på filstørrelsen. Etter eksporteringen er ferdig vil filen dukke opp i den valgte filstien din på din lokale maskin.
  • Ikke-interaktiv eksportering:
Det finnes også et alternativ for en ikke-interaktiv måte å eksportere en fil på inn i SAFE maskinen, noe som vil starte prosessen med eksportering umiddelbart.

Da skriver du hele kommandoen på en enkelt linje: safe-cli export-file --server <servername> --filename <file name> --output-dir <output directory path>
Fullt eksempel: safe-cli export-file --server serverenmin --filename "New Text Document.txt" --output-dir "C:\Users\brukernavnetmitt\Downloads"

Eksempelbilde på bruk av ikke-interaktiv eksportering.

Dette vil fungere så lenge du fyller inn servernavn, filnavn og filstien du ønsker å plassere filen i riktig. Filstien er litt annerledes på ulike operativsystem (Windows format ovenfor), men det skal fungere for ulike formatteringer helt fint.
Husk også fortsatt å ha gyldig token og SAFE VPN aktivert, ellers vil det feile.
  • Mer om eksportering:
Foreløpig kan man kun velge en fil om gangen for eksportering, men det skal endres slik at flere filer kan eksporteres etterhvert i utviklingen av produktet.

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 hver gang, 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.
  • Skjermbildene kan avvike noe fra hvordan det vil se ut etter fremtidig utvikling, men kommandoene bør være de samme.

Gi beskjed hvis du opplever problemer eller tenker dette dokumentet bør oppdateres.