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 klastra o identyfikatorze site_key. Aktualne wpierane są następujące klastry:

Pobieranie listy zawartości folderu

GET:
https://data.plgrid.pl/list/[site_key]/[folder_path]
Jako parametr wywołania należy przekazać zawartość cartyfikatu proxy w parametrze o nazwie 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
Przykładowy element zwracanego dokumentu JSON: 
{"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/[site_key]/net/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/[site_key]/net/people/plguserlogin/ -H "PROXY:`cat grid_proxy | base64 | tr -d '\n'`"

Pobieranie pliku z klastra

GET:
https://data.plgrid.pl/download/[site_key]/[file_path]
Jako parametr wywołania należy przekazać zawartość cartyfikatu proxy w parametrze o nazwie 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/[site_key]/net/people/plguserlogin/graph.png
--data-urlencode proxy="`cat grid_proxy`"

Zapisywanie pliku na klaster

POST:
https://data.plgrid.pl/upload/[site_key]/[target_folder_path]
Obecnie ładowanie plików na serwer przez API jest ograniczone do objęctości 256 MB. Operacja zakłada przekazanie następujących parametrów wywołania POST:
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.
Przykład wywołania operacji z użyciem narzędzia linii komend curl 
curl -X POST https://data.plgrid.pl/upload/[site_key]/net/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/[site_key]/net/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/[site_key]/net/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/[site_key]/[target_folder_path]
Pozwala założyć nowy folder o wskazanej ścieżce i nazwie, w systemie plików klastra. Są następujące parametry wywołania:
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.
Przykład wywołania operacji z użyciem narzędzia linii komend curl 
curl -X POST https://data.plgrid.pl/mkdir/[site_key]/net/people/plguserlogin/zzz/eeee -F proxy="`cat grid_proxy`"
curl -X POST https://data.plgrid.pl/mkdir/[site_key]/net/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/[site_key]/[file_or_folder_path]
Powoduje usunięcie wskazanego zbioru z klastra. Parametry wywołania są następujące:
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
Przykład wywołania operacji z użyciem narzędzia linii komend curl 
curl -X DELETE https://data.plgrid.pl/remove/[site_key]/net/people/plguserlogin/graph.png -F proxy="`cat grid_proxy`"
curl -X DELETE https://data.plgrid.pl/remove/[site_key]/net/people/plguserlogin/zzz/ -F proxy="`cat grid_proxy`"
-F "is_dir=true"

Transfer (kopiowanie) pliku

PUT:
https://data.plgrid.pl/transfer/[site_key]/[sourcke_file_path]
Operacja kopiuje plik z klastra do innego miejsca na klastrze. Parametry wywołania są następujące:
proxy
Zawartość cartyfikatu proxy użytkownika, na rzecz którego wykonujemy transfer
destination_path
Wymagany parametr który powinien być ścieżką do miejsca zapisania kopii pliku. W ścieżce powinna się znaleźć nazwa nowego pliku
locale
Opcjonalny parametr, którego wartość można ustawić na 'en' aby otrzymywać komunikaty zwrotne w języku angielskim
Przykład wywołania operacji z użyciem narzędzia linii komend curl 
curl -X PUT https://data.plgrid.pl/transfer/[site_key]/net/people/plguserlogin/dir1/file.txt -F proxy="`cat grid_proxy`"
-F "destination_path=/net/people//plguserlogin/dir2/copied_file.txt"

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ą: 

read -s p && echo $p | ssh -l plguserlogin pro.cyfronet.pl "grid-proxy-init -q -pwstdin && cat /tmp/x509up_u\`id -u\`" > grid_proxy && unset p
Należy najpierw podać swój passphrase do klucza prywatnego (właśnie to drugie hasło z ekranu logowania OpenId). Na ekranie nie pojawi się żadne wezwanie aby podać passphrase, ale możesz go wpisać bezpiecznie, wprowadzone hasło będzie ukryte na twoim ekranie. Następnie proszę zaloguj się do swojego konta na Prometeuszu, podając hasło do plguserlogin na klastrze. 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.