This is an old revision of the document!
Naše API běží na adrese https://api.vpsfree.cz. Pomocí API lze vykonat většinu 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://vpsadmin.vpsfree.cz API využívá a pro každý úkon jej volá.
Dokumentace API, tzn. seznam objektů, možných akcí, vstupních a výstupních parametrů je k vidění na https://api.vpsfree.cz/v1.0/.
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.
API je postaveno na námi vyvinutém frameworku HaveAPI, které vytváří samodokumentující se API, což znamená, že lze využít předpřipravené generické klienty:
Ukázka použití je vždy v README.md
každého klienta. Obecně se klientovi
předá URL k API, poté si sám stáhne dokumentaci a podle ní se nastaví.
API je RESTful, takže pro jednoduché úkony lze využít i libovolný REST klient. Popis vlastního protokolu pro přenos dat, který HaveAPI klienti abstrahují, je k nahlédnutí v dokumentaci.
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ě, ukládání hesla na disk či neustálé opisování není dobrý nápad.
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í:
Typ tokenu a časový interval, o který se prodlužuje, si volí klient.
Klient pro Ruby obsahuje i CLI.
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 -dev
či -devel
).
$ brew install openssl $ sudo gem install eventmachine -- --with-opt-include="/usr/local/opt/openssl/"
Nainstalovat jej lze pomocí ruby gems:
$ gem install vpsfree-client
Po instalaci by v $PATH
měl být k dispozici vpsfreectl
. Pokud tomu tak
není, lze to jednoduše napravit:
$ gem env | grep "EXECUTABLE DIRECTORY"
Tento příkaz vypíše, kde jsou uloženy spustitelné soubory instalované přes
gem
. Stačí tedy onen adresář přidat do $PATH
, např.:
$ PATH="$PATH:/home/user/.gem/ruby/2.0.0/bin"
$ vpsfreectl --help Usage: vpsfreectl [options] <resource> <action> [objects ids] [-- [parameters]] -u, --api URL API URL -a, --auth METHOD Authentication method --list-versions List all available API versions --list-auth-methods [VERSION] List available authentication methods --list-resources [VERSION] List all resource in API version --list-actions [VERSION] List all resources and actions in API version --version VERSION Use specified API version -c, --columns Print output in columns -H, --no-header Hide header row -L, --list-parameters List output parameters -o, --output PARAMETERS Parameters to display, separated by a comma -r, --rows Print output in rows -s, --sort PARAMETER Sort output by parameter --save Save credentials to config file for later use --raw Print raw response as is --timestamp Display Datetime parameters as timestamp --utc Display Datetime parameters in UTC --localtime Display Datetime parameters in local timezone --date-format FORMAT Display Datetime in custom format -v, --[no-]verbose Run verbosely --client-version Show client version --protocol-version Show protocol version --check-compatibility Check compatibility with API server -h, --help Show this message Commands: vps remote_console VPS_ID Open VPS remote console 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
Jméno a heslo buď předáme parametry --username
a --password
, nebo
parametry vynecháme a program k zadání údajů uživatele vybídne.
$ vpsfreectl --auth basic user current
Autentizace přes tokeny zavádí několik nových přepínačů:
$ vpsfreectl --auth token --help ... -a, --auth METHOD Authentication method -s, --save Save credentials to config file for later --username USER User name --password PASSWORD Password --token TOKEN Token --token-lifetime LIFETIME Token lifetime, defaults to renewable_auto --token-interval SECONDS How long will token be valid in seconds --new-token Request new token --token-via VIA Send token as a query parameter or in HTTP header (query_param, header) ...
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 ~/.haveapi-client.yml
a při dalším spuštění je
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
~/.haveapi-client.yml
může token získat a použít.
Objekty a akce mají názvy stejné jako v dokumentaci, jen malými písmeny a
místo mezer se píší podtržítka. Každá akce má svoje vstupní a výstupní parametry.
Zobrazí se přepínačem --help
, pokud je zadán název objektu i akce:
$ vpsfreectl vps list --help ... Action description: List VPS Input parameters: --offset OFFSET The offset of the first object --limit LIMIT The number of objects to retrieve --node NODE Filter by node --location LOCATION Filter by location --environment ENVIRONMENT Filter by environment --os-template OS_TEMPLATE OS template --object-state OBJECT_STATE Object state -h, --help Show this message Output parameters: id user VPS owner hostname VPS hostname os_template dns_resolver DNS resolver the VPS will use node Node VPS will run on dataset Dataset the VPS resides in created_at memory Minimally 1024, maximally 12288, step size is 128 swap Minimally 0, maximally 12288, step size is 128 cpu Minimally 1, maximally 8, step size is 1 maintenance_lock maintenance_lock_reason object_state expiration_date A date after which the state will progress running process_count used_memory in MB used_disk in MB ...
Můžeme tedy VPS filtrovat dle serveru, lokace, prostředí, distribuce, stavu 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 ID Label 3 Praha 4 Brno 5 Playground
Nyní zobrazíme VPS nacházející se v lokaci Praha:
$ vpsfreectl vps list -- --location 3
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 -c
, --columns
pro sloupce a -r
, --rows
pro řádky.
Ukázka výpisu do sloupců (v tomto případě je přepínač --columns
nadbytečný – jelikož výstup obsahuje více objektů, zvolí se automaticky):
$ vpsfreectl vps list --columns ID Label 3 Praha 4 Brno 5 Playground
Ukázka výpisu do řádků:
$ vpsfreectl location list --rows ID: 3 Label: Praha ID: 4 Label: Brno ID: 5 Label: Playground
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 -H
,
--no-header
.
Přepínačem -o
, --output
se nastavuje, které výstupní parametry akce
a v jakém pořadí budou vypsány. Názvy parametrů se oddělují čárkou.
$ vpsfreectl vps list -o id,hostname,node,os_template VPS id: 4710 Hostname: vps Node: node7.prg (#108) OS template: CentOS 7 (#43)
Přepínačem -s
, --sort
lze výstup vzestupně seřadit podle určitého
parametru (na straně klienta).
$ vpsfreectl os_template list --sort label ID Label Info Supported 42 Arch Linux [TEST] - 0 24 CentOS 6 - 1 43 CentOS 7 - 1 20 Debian 6 - 1 31 Debian 7 - 1 38 Debian 7 [TEST] - 0 46 Debian 8 - 1 33 Fedora 20 - 1 40 Fedora 22 - 1 14 Gentoo 13.0 - 1 37 Gentoo [TEST] - 0 32 OpenSUSE 12.3 - 1 26 Scientific Linux 6.6 - 1 45 Scientific Linux 7 - 0 30 Ubuntu 12.04 - 1 35 Ubuntu 14.04 - 1 39 Ubuntu 14.04 [TEST] - 0 47 openSUSE 13.2 [TEST] - 0
Klient obsahuje několik přepínačů, kterými se volí formát data a času,
vrací-li akce parametr typu Datetime
.
--utc
--localtime
--timestamp
--date-format FORMAT
- formát dle Time#strftimeNásledují skripty demonstrují možnosti využití API. Tyto skripty lze spouštět odkudkoli – manuálně, z cronu, apod.
#!/usr/bin/env ruby # Stažení poslední (nejnovější) zálohy všech VPS. require 'vpsfree/client' api = VpsFree::Client::Client.new api.authenticate(:token, token: 'PUT YOUR TOKEN HERE') downloads = [] api.dataset.list(role: :hypervisor).each do |ds| last_snapshot = ds.snapshot.list.last dl = api.snapshot_download.create(snapshot: last_snapshot.id) unless dl.api_response.ok? warn "#{ds.name}@#{last_snapshot.created_at}: #{dl.api_response.message}" 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 "Waiting for the downloads to be ready..." loop do sleep(5*60) downloads.delete_if do |id| dl = api.snapshot_download.find(id) unless dl.api_response.ok? warn "Download #{id} has failed" next(true) # remove from the list end if dl.ready puts "Downloading #{id} to #{dl.file_name} (#{dl.size / 1024} GB)" `wget "#{dl.url}"` dl.delete true else false end end break if downloads.empty? end puts "Done"
#!/usr/bin/env ruby # Denní snapshotovaní NASu se 7 denní historií require 'vpsfree/client' api = VpsFree::Client::Client.new api.authenticate(:token, token: 'PUT YOUR TOKEN HERE') api.dataset.list(role: :primary).each do |ds| # 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: {count: true}) 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 "Delete #{ds.name}@#{snap.created_at}" snap.delete deleted += 1 # Opět naivní čekání na provedení akce. sleep(30) end end end