Differences

This shows you the differences between two versions of the page.

--- navody:vps:api [2016/10/21 13:28] – Doplnění návodu na instalaci vpsfree-clienta ve Windows 10 pomocí Linux subsystemu (viz IRC 21.1.2016) tierraverde
+++ 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://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 =====
-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/v2.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.
-===== Práce s API =====
-API je postaveno na námi vyvinutém frameworku
-[[https://github.com/vpsfreecz/haveapi|HaveAPI]], které vytváří
-[[https://github.com/vpsfreecz/haveapi#what-is-a-self-describing-api|samodokumentující]]
-se API, což znamená, že lze využít předpřipravené generické
-klienty:
-  * Ruby - https://github.com/vpsfreecz/vpsfree-client
-  * PHP - https://github.com/vpsfreecz/haveapi-client-php
-  * JavaScript - https://github.com/vpsfreecz/haveapi-client-js
-  * Souborový systém založený na FUSE - https://github.com/vpsfreecz/haveapi-fs
-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 [[wp>Representational state transfer|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
-[[https://api.vpsfree.cz/doc/protocol.md|dokumentaci]].
-===== 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ě, 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í:
-  * 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, si volí klient.
-===== CLI =====
-[[https://github.com/vpsfreecz/vpsfree-client|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'').
-<note>
-Na OS X je nutné nainstalovat OpenSSL přes [[http://brew.sh/|Homebrew]] a až
-poté se dá nainstalovat EventMachine (gem, jenž klient vyžaduje).
-<code>
-$ brew install openssl
-$ sudo gem install eventmachine -- --with-opt-include="/usr/local/opt/openssl/"
-</code>
-</note>
-Nainstalovat jej lze pomocí ruby gems:
-<code>
-$ gem install vpsfree-client
-</code>
-==== Instalace ve Windows 10 využitím Ubuntu Linux subsystem ====
-=== Instalace Ubuntu (Linux subsystemu Windows 10) ===
-  - ve Windows 10 povolit developer mode, nechat nainstalovat
-  - přes Programy a funkce otevřít přidání součástí Windows, úplně dole zvolit Linux subsystem, nechat nainstalovat a restartovat počítač
-  - po restartu jako admin spustit v nabídce Start bash
-  - vytvořit Unix username a heslo
-  - stisknout y a nechat nainstalovat základ Ubuntu
-=== Instalace závislostí ===
-<code bash>
-sudo apt-get install ruby2.0 ruby2.0-dev libssl-dev make g++
-</code>
-=== Quick & Dirty fix pro nastavení ruby2.0 jako výchozího namísto 1.9 ===
-<code bash>
-sudo rm /usr/bin/ruby /usr/bin/gem /usr/bin/irb /usr/bin/rdoc /usr/bin/erb
-sudo ln -s /usr/bin/ruby2.0 /usr/bin/ruby
-sudo ln -s /usr/bin/gem2.0 /usr/bin/gem
-sudo ln -s /usr/bin/irb2.0 /usr/bin/irb
-sudo ln -s /usr/bin/rdoc2.0 /usr/bin/rdoc
-sudo ln -s /usr/bin/erb2.0 /usr/bin/erb
-sudo gem update --system
-sudo gem pristine --all
-</code>
-Zdroj: http://blog.costan.us/2014/04/restoring-ruby-20-on-ubuntu-1404.html
-=== Instalace vpsfree-client ===
-<code bash>
-sudo gem install vpsfree-client
-</code>
-----
-Po instalaci by v ''$PATH'' měl být k dispozici ''vpsfreectl''. Pokud tomu tak
-není, lze to jednoduše napravit:
-<code>
-$ gem env | grep "EXECUTABLE DIRECTORY"
-</code>
-Tento příkaz vypíše, kde jsou uloženy spustitelné soubory instalované přes
-''gem''. Stačí tedy onen adresář přidat do ''$PATH'', např.:
-<code>
-$ PATH="$PATH:/home/user/.gem/ruby/2.0.0/bin"
-</code>
-==== Použití ====
-<code>
-$ 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
-</code>
-Výběrem autentizační metody nebo objektu či akce se v nápovědě přibydou
-další možné přepínače:
-<code>
-$ vpsfreectl --auth basic --help
-$ vpsfreectl vps --help
-$ vpsfreectl vps list --help
-</code>
-==== Autentizace ====
-=== HTTP basic ===
-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.
-<code>
-$ vpsfreectl --auth basic user current
-</code>
-=== Tokeny ===
-Autentizace přes tokeny zavádí několik nových přepínačů:
-<code>
-$ 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)
-    ...
-</code>
-Jméno a heslo opět nemusíme předávat jako parametry, program se na ně zeptá.
-Jednorázový token:
-<code>
-$ vpsfreectl --auth token user current
-</code>
-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:
-<code>
-$ vpsfreectl --auth token --save user current
-</code>
-Token se uložil do souboru ''~/.haveapi-client.yml'' a při dalším spuštění je
-automaticky načten:
-<code>
-$ vpsfreectl user current
-</code>
-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í:
-<code>
-$ vpsfreectl --auth token --save --token-interval $((24*60*60)) user current # 1 den
-</code>
-Nebo rovnou token s platností neomezenou:
-<code>
-$ vpsfreectl --auth token --save --token-lifetime permanent user current
-</code>
-<note warning>
-Na token s neomezenou platností je třeba dávat pozor, protože kdokoli s
-přístupem k ''~/.haveapi-client.yml'' může token získat a použít.
-</note>
-==== Akce a parametry ====
-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:
-<code>
-$ 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
-...
-</code>
-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:
-<code>
-$ vpsfreectl vps list -- --limit 3
-</code>
-Pokud bychom chtěli filtrovat např. dle lokace, nejdříve si je vypíšeme:
-<code>
-$ vpsfreectl location list
- ID  Label
-  Praha
-  Brno
-  Playground
-</code>
-Nyní zobrazíme VPS nacházející se v lokaci Praha:
-<code>
-$ vpsfreectl vps list -- --location 3
-</code>
-==== 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 ''-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):
-<code>
-$ vpsfreectl vps list --columns
- ID  Label
-  Praha
-  Brno
-  Playground
-</code>
-Ukázka výpisu do řádků:
-<code>
-$ vpsfreectl location list --rows
-    ID:  3
- Label:  Praha
-    ID:  4
- Label:  Brno
-    ID:  5
- Label:  Playground
-</code>
-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%%''.
-==== Výběr parametrů k zobrazení ====
-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.
-<code>
-$ vpsfreectl vps list -o id,hostname,node,os_template
-      VPS id:  4710
-    Hostname:  vps
-        Node:  node7.prg (#108)
- OS template:  CentOS 7 (#43)
-</code>
-==== Řazení ====
-Přepínačem ''-s'', ''%%--sort%%'' lze výstup vzestupně seřadit podle určitého
-parametru (na straně klienta).
-<code>
-$ vpsfreectl os_template list --sort label
- ID  Label                  Info   Supported
-  Arch Linux [TEST]      -      0
-  CentOS 6               -      1
-  CentOS 7               -      1
-  Debian 6               -      1
-  Debian 7               -      1
-  Debian 7 [TEST]        -      0
-  Debian 8               -      1
-  Fedora 20              -      1
-  Fedora 22              -      1
-  Gentoo 13.0            -      1
-  Gentoo [TEST]          -      0
-  OpenSUSE 12.3          -      1
-  Scientific Linux 6.6   -      1
-  Scientific Linux 7     -      0
-  Ubuntu 12.04           -      1
-  Ubuntu 14.04           -      1
-  Ubuntu 14.04 [TEST]    -      0
-  openSUSE 13.2 [TEST]   -      0
-</code>
-==== Formát času a data ====
-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 [[http://ruby-doc.org/core-2.3.0/Time.html#method-i-strftime|Time#strftime]]
-===== Aktualizace =====
-Pro využití nových vlastností je potřeba klienta občas aktualizovat, což se
-provede příkazem
-<code>
-$ gem update vpsfree-client
-</code>
-Následně můžeme odstranit starou verzi:
-<code>
-$ gem cleanup vpsfree-client
-</code>
-Tento příkaz odstraní pouze staré verze gemu ''vpsfree-client'', ale jeho
-závislosti zůstanou. Pro odstranění všech starých gemů použijte příkaz
-<code>
-$ gem cleanup -n  # vypíše, které gemy by smazal
-$ gem cleanup  # smaže gemy
-</code>
-===== Souborový systém ======
-''haveapi-fs'' je souborový systém založený na FUSE, tzn. umožňuje připojit
-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 se stejným způsobem
-jako CLI, má jen jiný název:
-<code>
-$ gem install haveapi-fs
-</code>
-==== Použití ====
-Použití ''haveapi-fs'' je podrobně popsáno v
-[[https://github.com/vpsfreecz/haveapi-fs#usage|README.md]], zde jen ve
-zkratce.
-<code>
-$ haveapi-fs https://api.vpsfree.cz /mnt/api.vpsfree.cz
-Username: mujlogin
-Password:
-$ cd /mnt/api.vpsfree.cz
-$ 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
-</code>
-V každém adresáři se nachází soubory ''help.{html,txt,md,man}'', které popisují co
-aktuální adresář obsahuje.
-<code>
-$ cat vps/5685/hostname
-moje-vps
-$ echo lepsi-hostname > vps/5685/hostname
-$ echo 1 > vps/5685/save
-$ cat vps/5685/actions/update/status
-$ cat vps/5685/hostname
-lepsi-hostname
-</code>
-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í/úpravu objektů lze použít YAML soubory
-''create.yml'', resp. ''update.yml''. Tyto soubory obsahují parametry jako
-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.
-<note>
-Ač jsou tyto ukázky stále validní, klient v CLI už obsahuje
-[[navody:vps:datasety#stahovani_zaloh|příkazy]], díky kterým je stahování záloh
-ještě jednodušší.
-</note>
-==== Každodenní stahování záloh VPS ====
-<code>
-#!/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"
-</code>
-==== Denní zálohování NASu s týdenní historií ====
-<code>
-#!/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
-</code>

Knowledge base

User Tools

Site Tools

Differences

Page Tools