Dokumentacja API
Uwaga: wszystkie poniższe operacje wymagają przekazania tzw. certyfikatu proxy użytkownika.
Więcej
informacji na jego temat znajduje się na końcu dokumentacji. W przykładach zakładamy, że znajduje się on w pliku
grid_proxy
w katalogu bieżącym. Certyfikat ten można przekazać przez parametr wywołania, o nazwie
proxy
lub przez nagłówek
(header)
o nazwie
PROXY
.
Obie te możliwości można zobaczyć w przykładach. W tym drugim przypadku treść proxy musi zostać odpowiednio
zakodowana.
Wszystkie poniższe operacje zdalne na serwerze PLGData wykonywane są przy pomocy protokołu HTTPS, poprzez wywołanie jednej z operacji HTTP (np. GET lub POST) na wskazany URL, z przekazaniem wymienionych parametrów.
Ścieżki do folderów i plików podane w przykładach poniżej będą przez serwer rozumiane jako prowadzące do
systemu plików komputera Zeus. W celu odwołania się do plików czy folderów na komputerze Prometheus, należy
nieco zmodyfikować adresy URL w poniższych przykładach, dodając nazwę
prometheus
zaraz po nazwie operacji. Przykładowo, pobieranie listy zawartości folderu zlokalizowanego na komputerze
Prometheus wymaga przekazania URL w następującej postaci:
https://data.plgrid.pl/list/prometheus/[folder_path]
,
a załadowanie pliku do katalogu na dysku komputera Prometheus wymaga użycia URL w postaci:
https://data.plgrid.pl/upload/prometheus/[target_folder_path]
.
Analogicznie dla pozostałych operacji.
Pobieranie listy zawartości folderu
-
GET:
-
https://data.plgrid.pl/list/[folder_path]
proxy
.
Wywołanie operacji zwraca dokument JSON z zawartością wskazanego folderu,
z uwzględnieniem podfolderów i zbiorów ukrytych. Dokument
zawiera listę zbiorów, dla każdego zbioru prezentując następujące informacje:
- rights
-
Lista praw dostępu, w
formacie POSIX
tj.
drwxrwxrwx
ze znakiem-
w miejscu braku danych uprawnień - owner
-
Nazwa użytkownika, który jest posiadaczem zbioru. Dla tego użytkownika działa pierwsza trójka praw dostępu
wymienionych w polu
rights
- group
-
Nazwa grupy systemowej, do której należy zbiór. Dla wszystkich użytkowników należących do tej grupy działa
druga trójka praw dostępu wymienionych w polu
rights
- size
- Wielkość zbioru w bajtach
- modification_date
- Data ostatniej modyfikacji pliku, podana w języku angielskim, w formacie: MMM [D]D HH:mm
- name
- Nazwa zbioru
- is_dir
-
Flaga logiczna informująca, czy zbiór jest folderem czy plikiem. Podobną informację można uzyskać analizując
pierwszą literę wartości pola
rights
{"rights":"drwxr-xr-x","owner":"plguserlogin","group":"plgrid","size":2048,"modification_date":"May 6 18:24","name":"my_folder","is_dir":true}Przykład wywołania operacji z użyciem narzędzia linii komend
curl
curl -X GET https://data.plgrid.pl/list/people/plguserlogin/ --data-urlencode proxy="`cat grid_proxy`"Przykład wersji z przekazaniem certyfikatu proxy przez nagłówek wywołania operacji:
curl -X GET https://data.plgrid.pl/list/people/plguserlogin/ -H "PROXY:`cat grid_proxy | base64 | tr -d '\n'`"
Pobieranie pliku z klastra
-
GET:
-
https://data.plgrid.pl/download/[file_path]
proxy
.
Opercja uruchamia pobieranie wskazanego pliku z klastra, poprzez strumieniowane łącze szyfrowane. Klient wywołania
operacji jest zobowiązany odpowiednio obsłużyć pobieranie i zapisywanie danych ze strumienia.
Przykład wywołania operacji z użyciem narzędzia linii komend
curl
curl -X GET https://data.plgrid.pl/download/people/plguserlogin/graph.png --data-urlencode proxy="`cat grid_proxy`"
Zapisywanie pliku na klaster
-
POST:
-
https://data.plgrid.pl/upload/[target_folder_path]
- file
- Ładowany plik, analogicznie jak w przypadku wysyłania pliku formularzem, w formacie multipart
- proxy
- Zawartość cartyfikatu proxy użytkownika, na rzecz którego wysyłamy plik na klaster
- locale
- Opcjonalny parametr, którego wartość można ustawić na 'en' aby otrzymywać komunikaty zwrotne w języku angielskim
- recursive
- Opcjonalny parametr, którego użycie spowoduje utworzenie docelowego folderu, rekursywnie (tj. z wszystkimi ew. pośrednimi folderami), jeśli wskazany folder docelowy jeszcze nie istnieje na klastrze.
curl
curl -X POST https://data.plgrid.pl/upload/people/plguserlogin/zzzz/ -F proxy="`cat grid_proxy`" -F "file=@graph.png"Przykład wersji z przekazaniem certyfikatu proxy przez nagłówek wywołania operacji:
curl -X POST https://data.plgrid.pl/upload/people/plguserlogin/zzzz/ -H "PROXY:`cat grid_proxy | base64 | tr -d '\n'`" -F "file=@graph.png"Tu z kolei została użyta alternatywna opcja rekursywnego tworzenia folderów:
curl -X POST https://data.plgrid.pl/upload/people/plguserlogin/zzzz/1/2/3/ -F proxy="`cat grid_proxy`" -F "file=@graph.png" -F locale=en -F recursive=true
Tworzenie nowego folderu
-
POST:
-
https://data.plgrid.pl/mkdir/[target_folder_path]
- proxy
- Zawartość cartyfikatu proxy użytkownika, na rzecz którego wykonujemy operację tworzenia folderu
- recursive
- Opcjonalny parametr, którego użycie spowoduje utworzenie docelowego folderu rekursywnie - tj. zostaną utworzone także wszystkie pośrednie nadfoldery wskazane w ścieżce.
curl
curl -X POST https://data.plgrid.pl/mkdir/people/plguserlogin/zzz/eeee -F proxy="`cat grid_proxy`"
curl -X POST https://data.plgrid.pl/mkdir/people/plguserlogin/zzz/eeee/1/2 -F proxy="`cat grid_proxy`" -F recursive=true
Usuwanie pliku bądź folderu z klastra
-
DELETE:
-
https://data.plgrid.pl/remove/[file_or_folder_path]
- proxy
- Zawartość cartyfikatu proxy użytkownika, na rzecz którego wykonujemy operację kasowania zbioru
- is_dir
-
Parametr ten jest wymagany, a jego wartość powinna być ustawiona na
true
, jeśli chcemy skasować folder. Jest to wymagane ponieważ protokół GridFTP, którego PLGData używa jako warstwy pośredniczącej w operacjach na plikach na klastrze, rozróżna operację kasowania pliku od operacji kasowania folderu. - locale
- Opcjonalny parametr, którego wartość można ustawić na 'en' aby otrzymywać komunikaty zwrotne w języku angielskim
curl
curl -X DELETE https://data.plgrid.pl/remove/people/plguserlogin/graph.png -F proxy="`cat grid_proxy`"
curl -X DELETE https://data.plgrid.pl/remove/people/plguserlogin/zzz/ -F proxy="`cat grid_proxy`" -F "is_dir=true"
Certyfikat proxy użytkownika PL-Grid
Certyfikat proxy X509 użytkownika PLGData jest generowany w chwili logowania się do usługi (drugie pole z hasłem). Aby skorzystać z przedstawionego API, trzeba ten certyfikat posiadać np. w postaci pliku, na komputerze, na którym wykonuje się polecenie (bądź kod) komunikujący się z API PLGData. Najłatwiej ów certyfikat proxy wygenerować komendą:ssh -l plguserlogin zeus.cyfronet.pl "grid-proxy-init -q -pwstdin && cat /tmp/x509up_u\`id -u\`" > grid_proxyNależy najpierw podać swoje hasło do konta
plguserlogin
na klastrze zeus, a następnie swój
passphrase
do klucza prywatnego (właśnie to drugie hasło z ekranu logowania OpenId).
UWAGA.
Przy użyciu powyższej komendy passphrase klucza nie jest maskowany na ekranie monitora.
Po wykonaniu polecenia aktualny certyfikat proxy powinien znajdować się na lokalnym komputerze, w katalogu
bieżącym, w pliku pod nazwą
grid_proxy
.
Będzie on ważny przez kolejnych dwanaście godzin.
ędzie on ważny przez kolejnych dwanaście godzin.