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.

Pobieranie listy zawartości folderu

GET:
https://data.plgrid.pl/list/[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/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]
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/people/plguserlogin/graph.png
--data-urlencode proxy="`cat grid_proxy`"

Zapisywanie pliku na klaster

POST:
https://data.plgrid.pl/upload/[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/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]
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/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]
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/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_proxy
Należ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.