This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
navody:vps:api [2015/09/11 10:33] – vytvořeno 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:// | ||
- | |||
- | 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. | ||
- | |||
- | 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 | ||
- | -r, --raw Print raw response as is | ||
- | -s, --save | ||
- | -v, --[no-]verbose | ||
- | --client-version | ||
- | -h, --help | ||
- | |||
- | 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 | ||
- | </ | ||
- | |||
- | ==== Akce a parametry ==== | ||
- | Objekty a akce mají názvy stejné jako v dokumentaci, | ||
- | místo mezer podtržítka. Každá akce má svoje vstupní a výstupní parametry. Ty | ||
- | vstupní nám zobrazí '' | ||
- | |||
- | < | ||
- | $ vpsfreectl vps list --help | ||
- | ... | ||
- | Action description: | ||
- | List VPS | ||
- | |||
- | Action 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 | ||
- | ... | ||
- | </ | ||
- | |||
- | 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 '' | ||
- | 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 | ||
- | ID | LABEL | ||
- | ---|----------- | ||
- | 3 | Praha | ||
- | 4 | Brno | ||
- | 5 | Playground | ||
- | </ | ||
- | |||
- | Nyní zobrazíme VPS nacházející se v lokaci Praha: | ||
- | |||
- | < | ||
- | $ vpsfreectl vps list -- --location 3 | ||
- | </ | ||
- | |||
- | ===== 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. | ||
- | |||
- | ==== Každodenní stahování záloh VPS ==== | ||
- | < | ||
- | # | ||
- | # Download latest backup of all VPSes. | ||
- | 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 | ||
- | |||
- | # Creation of the archives is now queued, it will take some time before they' | ||
- | # ready to download. Regularily check dl.ready. | ||
- | 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í ==== | ||
- | < | ||
- | # | ||
- | # Daily snapshots of NAS with 7 day history | ||
- | require ' | ||
- | |||
- | api = Vpsfree:: | ||
- | api.authenticate(: | ||
- | |||
- | api.dataset.list(role: | ||
- | # Make a new snapshot | ||
- | ds.snapshot.create | ||
- | |||
- | # Rotate old snapshots | ||
- | t = Time.now - 7 * 24 * 60 * 60 | ||
- | snapshots = ds.snapshot.list(meta: | ||
- | deleted = 0 | ||
- | | ||
- | snapshots.each do |snap| | ||
- | # Keep at least 7 snapshots | ||
- | break if snapshots.total_count - deleted < 7 | ||
- | | ||
- | # Delete snapshots older than one week | ||
- | if snap.created_at < t | ||
- | puts " | ||
- | snap.delete | ||
- | deleted += 1 | ||
- | end | ||
- | end | ||
- | end | ||
- | </ | ||
- | |||