Plgdata

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]

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. ędzie on ważny przez kolejnych dwanaście godzin.