This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
navody:vps:api [2016/07/31 13:15] – haveapi-fs Aither | navody:vps:api [Unknown date] (current) – removed - external edit (Unknown date) 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== API ====== | ||
- | |||
- | Naše API běží na adrese https:// | ||
- | akcí, stejně jako z webového rozhraní. V API aktuálně není zahrnuta pouze | ||
- | správa uživatelských profilů (adresa, e-mail, apod.) a datové přenosy. | ||
- | |||
- | Ve skutečnosti webové rozhraní běžící na https:// | ||
- | využívá a pro každý úkon jej volá. | ||
- | |||
- | ===== Dokumentace API ===== | ||
- | Dokumentace API, tzn. seznam objektů, možných akcí, vstupních a výstupních | ||
- | parametrů je k vidění na https:// | ||
- | |||
- | Bez přihlášení se zobrazuje seznam všech objektů, tj. i těch, se kterými můžou | ||
- | pracovat pouze administrátoři. Vpravo nahoře se lze přihlásit stejnými údaji | ||
- | jako do vpsAdminu a poté se zobrazí pouze objekty, akce a parametry, se | ||
- | kterými může aktuálně přihlášený uživatel pracovat. | ||
- | |||
- | ===== Práce s API ===== | ||
- | API je postaveno na námi vyvinutém frameworku | ||
- | [[https:// | ||
- | [[https:// | ||
- | se API, což znamená, že lze využít předpřipravené generické | ||
- | klienty: | ||
- | |||
- | * Ruby - https:// | ||
- | * PHP - https:// | ||
- | * JavaScript - https:// | ||
- | * Souborý systém založený na FUSE - https:// | ||
- | |||
- | Ukázka použití je vždy v '' | ||
- | předá URL k API, poté si sám stáhne dokumentaci a podle ní se nastaví. | ||
- | |||
- | API je [[wp> | ||
- | úkony lze využít i libovolný REST klient. Popis vlastního protokolu pro přenos | ||
- | dat, který HaveAPI klienti abstrahují, | ||
- | [[https:// | ||
- | |||
- | ===== Autentizace ===== | ||
- | Lze využívat dvě autentizační metody. Tou první a jednodušší z nich je HTTP | ||
- | basic. S každým požadavkem na API se musí zaslat jméno a heslo. Je to dobrá | ||
- | volba pro jednorázové akce, pokud je ale potřeba API volat vícekrát nebo | ||
- | automatizovaně, | ||
- | |||
- | Druhou metodou je autentizace přes tokeny. Funguje to tak, že klient nejprve | ||
- | požádá o vytvoření tokenu, k tomu potřebuje jméno a heslo. Jakmile dostane | ||
- | token, může jméno a heslo zapomenout a dále se autentizuje získaným tokenem. | ||
- | |||
- | Tokeny mohou být několika typů s různě dlouhou životností: | ||
- | |||
- | * fixed - platnost tokenu je pevně dána | ||
- | * renewable_manual - platnost tokenu lze manuálně prodloužit | ||
- | * renewable_auto - platnost tokenu je prodloužena při každém požadavku | ||
- | * permament - token je platný napořád, resp. dokud není smazán | ||
- | |||
- | Typ tokenu a časový interval, o který se prodlužuje, | ||
- | |||
- | ===== CLI ===== | ||
- | [[https:// | ||
- | Pro správnou funkci vyžaduje Ruby >= 2.0 a nainstalované hlavičkové soubory | ||
- | Ruby a OpenSSL (většinou balíčky s příponou '' | ||
- | |||
- | < | ||
- | Na OS X je nutné nainstalovat OpenSSL přes [[http:// | ||
- | poté se dá nainstalovat EventMachine (gem, jenž klient vyžaduje). | ||
- | |||
- | < | ||
- | $ brew install openssl | ||
- | $ sudo gem install eventmachine -- --with-opt-include="/ | ||
- | </ | ||
- | </ | ||
- | |||
- | Nainstalovat jej lze pomocí ruby gems: | ||
- | |||
- | < | ||
- | $ gem install vpsfree-client | ||
- | </ | ||
- | |||
- | Po instalaci by v '' | ||
- | není, lze to jednoduše napravit: | ||
- | |||
- | < | ||
- | $ gem env | grep " | ||
- | </ | ||
- | |||
- | Tento příkaz vypíše, kde jsou uloženy spustitelné soubory instalované přes | ||
- | '' | ||
- | |||
- | < | ||
- | $ PATH=" | ||
- | </ | ||
- | |||
- | ==== Použití ==== | ||
- | |||
- | < | ||
- | $ vpsfreectl --help | ||
- | Usage: vpsfreectl [options] < | ||
- | -u, --api URL API URL | ||
- | -a, --auth METHOD | ||
- | --list-versions | ||
- | --list-auth-methods [VERSION] | ||
- | List available authentication methods | ||
- | --list-resources [VERSION] | ||
- | --list-actions [VERSION] | ||
- | --version VERSION | ||
- | -c, --columns | ||
- | -H, --no-header | ||
- | -L, --list-parameters | ||
- | -o, --output PARAMETERS | ||
- | -r, --rows | ||
- | -s, --sort PARAMETER | ||
- | --save | ||
- | --raw Print raw response as is | ||
- | --timestamp | ||
- | --utc Display Datetime parameters in UTC | ||
- | --localtime | ||
- | --date-format FORMAT | ||
- | -v, --[no-]verbose | ||
- | --client-version | ||
- | --protocol-version | ||
- | --check-compatibility | ||
- | -h, --help | ||
- | |||
- | Commands: | ||
- | vps remote_console VPS_ID | ||
- | |||
- | Available resources: | ||
- | auth_token | ||
- | cluster | ||
- | cluster_resource | ||
- | dataset | ||
- | dataset.snapshot | ||
- | dataset.plan | ||
- | dataset_plan | ||
- | dns_resolver | ||
- | environment | ||
- | environment.config_chain | ||
- | environment.dataset_plan | ||
- | integrity_check | ||
- | integrity_fact | ||
- | integrity_object | ||
- | ip_address | ||
- | location | ||
- | mail_log | ||
- | mail_recipient | ||
- | mail_template | ||
- | mail_template.recipient | ||
- | node | ||
- | os_template | ||
- | pool | ||
- | snapshot_download | ||
- | transaction_chain | ||
- | transaction_chain.transaction | ||
- | user | ||
- | user.environment_config | ||
- | user.cluster_resource | ||
- | user.state_log | ||
- | user_session | ||
- | vps | ||
- | vps.state_log | ||
- | vps.config | ||
- | vps.feature | ||
- | vps.ip_address | ||
- | vps.mount | ||
- | vps.console_token | ||
- | vps_config | ||
- | </ | ||
- | |||
- | Výběrem autentizační metody nebo objektu či akce se v nápovědě přibydou | ||
- | další možné přepínače: | ||
- | |||
- | < | ||
- | $ vpsfreectl --auth basic --help | ||
- | $ vpsfreectl vps --help | ||
- | $ vpsfreectl vps list --help | ||
- | </ | ||
- | |||
- | ==== Autentizace ==== | ||
- | === HTTP basic === | ||
- | Jméno a heslo buď předáme parametry '' | ||
- | parametry vynecháme a program k zadání údajů uživatele vybídne. | ||
- | < | ||
- | $ vpsfreectl --auth basic user current | ||
- | </ | ||
- | |||
- | === Tokeny === | ||
- | Autentizace přes tokeny zavádí několik nových přepínačů: | ||
- | |||
- | < | ||
- | $ vpsfreectl --auth token --help | ||
- | ... | ||
- | -a, --auth METHOD | ||
- | -s, --save | ||
- | --username USER User name | ||
- | --password PASSWORD | ||
- | --token TOKEN Token | ||
- | --token-lifetime LIFETIME | ||
- | --token-interval SECONDS | ||
- | --new-token | ||
- | --token-via VIA Send token as a query parameter or in HTTP header (query_param, | ||
- | ... | ||
- | </ | ||
- | |||
- | Jméno a heslo opět nemusíme předávat jako parametry, program se na ně zeptá. | ||
- | |||
- | Jednorázový token: | ||
- | < | ||
- | $ vpsfreectl --auth token user current | ||
- | </ | ||
- | Po ukončení je token zapomenut a příště je nutné vyžádat další. Token pro | ||
- | takové použití postráda smysl. | ||
- | |||
- | Uložení tokenu: | ||
- | < | ||
- | $ vpsfreectl --auth token --save user current | ||
- | </ | ||
- | |||
- | Token se uložil do souboru '' | ||
- | automaticky načten: | ||
- | < | ||
- | $ vpsfreectl user current | ||
- | </ | ||
- | |||
- | Takový token ale do 20 minut expiruje a je nutné vyžádat si nový. Je možné si | ||
- | rovnou udělat token s delší platností: | ||
- | |||
- | < | ||
- | $ vpsfreectl --auth token --save --token-interval $((24*60*60)) user current # 1 den | ||
- | </ | ||
- | |||
- | Nebo rovnou token s platností neomezenou: | ||
- | < | ||
- | $ vpsfreectl --auth token --save --token-lifetime permanent user current | ||
- | </ | ||
- | |||
- | <note warning> | ||
- | Na token s neomezenou platností je třeba dávat pozor, protože kdokoli s | ||
- | přístupem k '' | ||
- | </ | ||
- | |||
- | ==== Akce a parametry ==== | ||
- | Objekty a akce mají názvy stejné jako v dokumentaci, | ||
- | místo mezer se píší podtržítka. Každá akce má svoje vstupní a výstupní parametry. | ||
- | Zobrazí se přepínačem '' | ||
- | |||
- | < | ||
- | $ vpsfreectl vps list --help | ||
- | ... | ||
- | Action description: | ||
- | List VPS | ||
- | |||
- | Input parameters: | ||
- | --offset OFFSET | ||
- | --limit LIMIT The number of objects to retrieve | ||
- | --node NODE Filter by node | ||
- | --location LOCATION | ||
- | --environment ENVIRONMENT | ||
- | --os-template OS_TEMPLATE | ||
- | --object-state OBJECT_STATE | ||
- | -h, --help | ||
- | |||
- | Output parameters: | ||
- | id | ||
- | user VPS owner | ||
- | hostname | ||
- | os_template | ||
- | dns_resolver | ||
- | node Node VPS will run on | ||
- | dataset | ||
- | created_at | ||
- | memory | ||
- | swap | ||
- | cpu Minimally 1, maximally 8, step size is 1 | ||
- | maintenance_lock | ||
- | maintenance_lock_reason | ||
- | object_state | ||
- | expiration_date | ||
- | running | ||
- | process_count | ||
- | used_memory | ||
- | used_disk | ||
- | ... | ||
- | </ | ||
- | |||
- | Můžeme tedy VPS filtrovat dle serveru, lokace, prostředí, | ||
- | a omezit počet zobrazených položek či stránkovat. | ||
- | |||
- | Parametry akcí jsou od parametrů klienta odděleny dvěmi pomlčkami '' | ||
- | Následující příkaz vypíše první tři VPS: | ||
- | |||
- | < | ||
- | $ vpsfreectl vps list -- --limit 3 | ||
- | </ | ||
- | |||
- | Pokud bychom chtěli filtrovat např. dle lokace, nejdříve si je vypíšeme: | ||
- | |||
- | < | ||
- | $ vpsfreectl location list | ||
- | | ||
- | 3 Praha | ||
- | 4 Brno | ||
- | 5 Playground | ||
- | </ | ||
- | |||
- | Nyní zobrazíme VPS nacházející se v lokaci Praha: | ||
- | |||
- | < | ||
- | $ vpsfreectl vps list -- --location 3 | ||
- | </ | ||
- | |||
- | ==== Formátování výstupu ==== | ||
- | Výstup lze formátovat buď to sloupců, nebo řádků. Ve výchozím stavu se pro | ||
- | zobrazení vícero objektů použijí sloupce a pro jeden objekt řádky. Formát se | ||
- | vybírá přepínači '' | ||
- | pro řádky. | ||
- | |||
- | Ukázka výpisu do sloupců (v tomto případě je přepínač '' | ||
- | nadbytečný -- jelikož výstup obsahuje více objektů, zvolí se automaticky): | ||
- | < | ||
- | $ vpsfreectl vps list --columns | ||
- | | ||
- | 3 Praha | ||
- | 4 Brno | ||
- | 5 Playground | ||
- | </ | ||
- | |||
- | Ukázka výpisu do řádků: | ||
- | < | ||
- | $ vpsfreectl location list --rows | ||
- | ID: 3 | ||
- | | ||
- | |||
- | ID: 4 | ||
- | | ||
- | |||
- | ID: 5 | ||
- | | ||
- | </ | ||
- | |||
- | Při použití ve skriptech by při formátování do sloupců mohla vadit hlavička | ||
- | s názvy parametrů. Její výpis můžeme potlačit přepínačem '' | ||
- | '' | ||
- | |||
- | ==== Výběr parametrů k zobrazení ==== | ||
- | Přepínačem '' | ||
- | a v jakém pořadí budou vypsány. Názvy parametrů se oddělují čárkou. | ||
- | |||
- | < | ||
- | $ vpsfreectl vps list -o id, | ||
- | VPS id: 4710 | ||
- | Hostname: | ||
- | Node: node7.prg (#108) | ||
- | OS template: | ||
- | </ | ||
- | |||
- | ==== Řazení ==== | ||
- | Přepínačem '' | ||
- | parametru (na straně klienta). | ||
- | |||
- | < | ||
- | $ vpsfreectl os_template list --sort label | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | </ | ||
- | |||
- | ==== Formát času a data ==== | ||
- | Klient obsahuje několik přepínačů, | ||
- | vrací-li akce parametr typu '' | ||
- | |||
- | * '' | ||
- | * '' | ||
- | * '' | ||
- | * '' | ||
- | |||
- | ===== Aktualizace ===== | ||
- | |||
- | Pro využití nových vlastností je potřeba klienta občas aktualizovat, | ||
- | provede příkazem | ||
- | |||
- | < | ||
- | $ gem update vpsfree-client | ||
- | </ | ||
- | |||
- | Následně můžeme odstranit starou verzi: | ||
- | |||
- | < | ||
- | $ gem cleanup vpsfree-client | ||
- | </ | ||
- | |||
- | Tento příkaz odstraní pouze staré verze gemu '' | ||
- | závislosti zůstanou. Pro odstranění všech starých gemů použijte příkaz | ||
- | |||
- | < | ||
- | $ gem cleanup -n # vypíše, které gemy by smazal | ||
- | $ gem cleanup | ||
- | </ | ||
- | |||
- | ===== Souborový systém ====== | ||
- | '' | ||
- | API jako souborový systém z userspace. Objekty, akce a jejich parametry můžeme | ||
- | procházet jako adresáře a soubory v libovolném programu. Instaluje stejným způsobem | ||
- | jako CLI, má jen jiný název: | ||
- | |||
- | < | ||
- | $ gem install haveapi-fs | ||
- | </ | ||
- | |||
- | ==== Použití ==== | ||
- | Použití '' | ||
- | [[https:// | ||
- | zkratce. | ||
- | |||
- | < | ||
- | $ haveapi-fs https:// | ||
- | Username: mujlogin | ||
- | Password: | ||
- | |||
- | $ cd / | ||
- | $ ls -1 | ||
- | auth_token | ||
- | cluster | ||
- | cluster_resource | ||
- | dataset | ||
- | dataset_plan | ||
- | dns_resolver | ||
- | environment | ||
- | help.html | ||
- | help.man | ||
- | help.md | ||
- | help.txt | ||
- | ip_address | ||
- | language | ||
- | location | ||
- | mail_template | ||
- | migration_plan | ||
- | node | ||
- | object_history | ||
- | os_template | ||
- | snapshot_download | ||
- | transaction | ||
- | transaction_chain | ||
- | user | ||
- | user_session | ||
- | vps | ||
- | vps_config | ||
- | </ | ||
- | |||
- | V každém adresáři se nachází soubory '' | ||
- | aktuální adresář obsahuje. | ||
- | |||
- | < | ||
- | $ cat vps/ | ||
- | moje-vps | ||
- | |||
- | $ echo lepsi-hostname > vps/ | ||
- | $ echo 1 > vps/ | ||
- | $ cat vps/ | ||
- | 1 | ||
- | $ cat vps/ | ||
- | lepsi-hostname | ||
- | </ | ||
- | |||
- | Z ukázky výše lze vidět, že jednotlivé atributy objektů lze měnit jednoduše | ||
- | zapsáním do souboru. Akce uložení se vyvolá zapsáním jedničky, případně je to | ||
- | i spustitelný soubor, takže jej můžeme spustit. | ||
- | |||
- | Pro přehlednější vytváření/ | ||
- | '' | ||
- | hash a po uložení a uzavření souboru se příslušná akce provede. | ||
- | |||
- | Tímto způsobem lze provést jakoukoli operaci v API. | ||
- | |||
- | ===== Ukázky použití ===== | ||
- | Následují skripty demonstrují možnosti využití API. Tyto skripty lze | ||
- | spouštět odkudkoli -- manuálně, z cronu, apod. | ||
- | |||
- | < | ||
- | Ač jsou tyto ukázky stále validní, klient v CLI už obsahuje | ||
- | [[navody: | ||
- | ještě jednodušší. | ||
- | </ | ||
- | |||
- | ==== Každodenní stahování záloh VPS ==== | ||
- | < | ||
- | # | ||
- | # Stažení poslední (nejnovější) zálohy všech VPS. | ||
- | require ' | ||
- | |||
- | api = VpsFree:: | ||
- | api.authenticate(: | ||
- | |||
- | downloads = [] | ||
- | |||
- | api.dataset.list(role: | ||
- | last_snapshot = ds.snapshot.list.last | ||
- | |||
- | dl = api.snapshot_download.create(snapshot: | ||
- | | ||
- | unless dl.api_response.ok? | ||
- | warn "# | ||
- | next | ||
- | end | ||
- | |||
- | downloads << dl.id | ||
- | end | ||
- | |||
- | # vpsAdmin nyní vytváří tar.gz se zálohou a chvíli bude trvat, než jej lze | ||
- | # stáhnout. Pravidelně se kontroluje parametr ready u všech archivů. | ||
- | puts " | ||
- | loop do | ||
- | sleep(5*60) | ||
- | |||
- | downloads.delete_if do |id| | ||
- | dl = api.snapshot_download.find(id) | ||
- | | ||
- | unless dl.api_response.ok? | ||
- | warn " | ||
- | next(true) | ||
- | end | ||
- | | ||
- | if dl.ready | ||
- | puts " | ||
- | `wget "# | ||
- | dl.delete | ||
- | true | ||
- | | ||
- | else | ||
- | false | ||
- | end | ||
- | end | ||
- | | ||
- | break if downloads.empty? | ||
- | end | ||
- | |||
- | puts " | ||
- | </ | ||
- | |||
- | ==== Denní zálohování NASu s týdenní historií ==== | ||
- | < | ||
- | # | ||
- | # Denní snapshotovaní NASu se 7 denní historií | ||
- | require ' | ||
- | |||
- | api = VpsFree:: | ||
- | api.authenticate(: | ||
- | |||
- | api.dataset.list(role: | ||
- | # Vytvoření nového snapshotu | ||
- | ds.snapshot.create | ||
- | |||
- | # Naivní čekání na vytvoření snapshotu. Další možnost by byla kontrolovat | ||
- | # stav příslušného transaction chain. | ||
- | sleep(10) | ||
- | |||
- | # Smazání starších snapshotů | ||
- | t = Time.now - 7 * 24 * 60 * 60 | ||
- | snapshots = ds.snapshot.list(meta: | ||
- | deleted = 0 | ||
- | | ||
- | snapshots.each do |snap| | ||
- | # Necháme si nejméně 7 snapshotů | ||
- | break if snapshots.total_count - deleted < 7 | ||
- | | ||
- | # Smazaní přebytečných snapshotů staršich než 7 dní | ||
- | if snap.created_at < t | ||
- | puts " | ||
- | snap.delete | ||
- | deleted += 1 | ||
- | |||
- | # Opět naivní čekání na provedení akce. | ||
- | sleep(30) | ||
- | end | ||
- | end | ||
- | end | ||
- | </ | ||
- | |||