Differences

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

--- navody:vps:api [2015/09/12 10:03] – 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://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/v1/.
-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
-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.
-Nainstalovat jej lze pomocí ruby gems:
-<code>
-$ 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
-    -r, --raw                        Print raw response as is
-    -s, --save                       Save credentials to config file for later use
-    -v, --[no-]verbose               Run verbosely
-        --client-version             Show client version
-    -h, --help                       Show this message
-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>
-==== Akce a parametry ====
-Objekty a akce mají názvy stejné jako v dokumentaci, jen malými písmeny a
-místo mezer podtržítka. Každá akce má svoje vstupní a výstupní parametry. Ty
-vstupní nám zobrazí ''%%--help%%'', pokud je zadán název objektu i akce:
-<code>
-$ vpsfreectl vps list --help
-...
-Action description:
-List VPS
-Action 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
-...
-</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>
-===== 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 ====
-<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