Znalostní báze

Informace o sdružení vpsFree.cz, návody a nejčastější dotazy.

Uživatelské nástroje

Nástroje pro tento web

Umístění: Znalostní Báze vpsFree.cz » navody » vps » API
Historie: • API
navody:vps:api

Rozdíly

Zde můžete vidět rozdíly mezi vybranou verzí a aktuální verzí dané stránky.

Odkaz na výstup diff

Obě strany předchozí revizePředchozí verze
Následující verze		Předchozí verze
navody:vps:api [2021/12/09 12:08] – fix arch install instructions Aithernavody:vps:api [2025/03/24 20:40] (aktuální) – [Dokumentace API] Opraven link na dokumentaci API aither
Řádek 8: Řádek 8:
 ===== Dokumentace API ===== ===== Dokumentace API =====
 Dokumentace API, tzn. seznam zdrojů, možných akcí, vstupních a výstupních Dokumentace API, tzn. seznam zdrojů, možných akcí, vstupních a výstupních
-parametrů je k vidění na https://api.vpsfree.cz/v6.0/.+parametrů je k vidění na https://api.vpsfree.cz/.
  
 Bez přihlášení se zobrazuje seznam všech zdrojů, tj. i těch, se kterými můžou Bez přihlášení se zobrazuje seznam všech zdrojů, tj. i těch, se kterými můžou
Řádek 26: Řádek 26:
   * JavaScript - https://github.com/vpsfreecz/haveapi/tree/master/clients/js   * JavaScript - https://github.com/vpsfreecz/haveapi/tree/master/clients/js
   * Go - https://github.com/vpsfreecz/haveapi/tree/master/clients/go   * Go - https://github.com/vpsfreecz/haveapi/tree/master/clients/go
-  * Webové rozhraní z HaveAPI - https://github.com/vpsfreecz/haveapi-webui +  * Webové rozhraní z HaveAPI - https://github.com/vpsfreecz/haveapi-webui (zastaralé) 
-  * Souborový systém založený na FUSE - https://github.com/vpsfreecz/haveapi-fs+  * Souborový systém založený na FUSE - https://github.com/vpsfreecz/haveapi-fs (zastaralé)
  
 Ukázka použití je vždy v ''README.md'' každého klienta. Obecně se klientovi Ukázka použití je vždy v ''README.md'' každého klienta. Obecně se klientovi
Řádek 38: Řádek 38:
  
 ===== Autentizace ===== ===== Autentizace =====
-Lze využívat dvě autentizační metody. Tou první a jednodušší z nich je HTTP +API podporuje dva způsoby autentizace:
-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 +  * [[#http_basic|HTTP Basic]] 
-požádá o vytvoření tokenu, k tomu potřebuje jméno, heslo a připadně i TOTP.+  * [[#tokeny|Pomocí tokenů]] 
 + 
 +Konkrétní ukázky autentizace pro podporované programovací jazyky a CLI najdete 
 +v [[https://api.vpsfree.cz/v6.0/#auth|dokumentaci API]]. 
 + 
 +==== HTTP Basic ==== 
 +S každým požadavkem na API se musí zaslat jméno a heslo v HTTP hlavičce "Authorization". 
 +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. HTTP basic 
 +nelze použít, pokud máte aktivované dvoufaktorové ověřování. 
 + 
 +==== Tokeny ==== 
 +Klient nejprve požádá o vytvoření tokenu, k tomu potřebuje jméno, heslo a připadně i TOTP.
 Jakmile klient dostane token, může jméno a heslo zapomenout a dále se autentizuje Jakmile klient dostane token, může jméno a heslo zapomenout a dále se autentizuje
 získaným tokenem. získaným tokenem.
Řádek 50: Řádek 59:
 Tokeny mohou být několika typů s různě dlouhou životností: Tokeny mohou být několika typů s různě dlouhou životností:
  
-  * fixed - platnost tokenu je pevně dána +  * //fixed// - platnost tokenu je pevně dána 
-  * renewable_manual - platnost tokenu lze manuálně prodloužit +  * //renewable_manual// - platnost tokenu lze manuálně prodloužit 
-  * renewable_auto - platnost tokenu je prodloužena při každém požadavku +  * //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+  * //permament// - token je platný napořád, resp. dokud není smazán
  
 Typ tokenu a časový interval, o který se prodlužuje, si volí klient. Typ tokenu a časový interval, o který se prodlužuje, si volí klient.
  
-===== CLI ===== +===== Scopes ===== 
-[[https://github.com/vpsfreecz/vpsfree-client|Klient pro Ruby]] obsahuje i CLI. +U autentizačních tokenů si můžeme zvolit, jaké akce bude token mít k dispozici. 
-Pro správnou funkci vyžaduje Ruby >= 2.0 a nainstalované hlavičkové soubory +To se může hodit u tokenů s dlouhou nebo permanentní platností. Každá akce 
-Ruby, OpenSSL a ncurses (většinou balíčky s příponou ''-dev'' či ''-devel'').+má svůj //scope//, jehož název najdeme v dokumentaci. Dostupné scope se nastavuje, 
 +když žádáme o nový token, tj. zasílá se společně s přihlašovacími údaji.
  
-==== Linux ====+Ukázky možných scopes:
  
-==== Ubuntu 20.04 ====+  * ''all'' povolí přístup ke všem akcím, toto je výchozí hodnota 
 +  * prázdný scope, přístup je povolen jen k akci ''user#current'', což zobrazí info o aktuálním uživateli; toto se využívá pro přihlášení do Discourse a KB 
 +  * ''vps#show'' povolí zobrazení info o jakékoli VPS 
 +  * ''vps#show:vps_id=123'' info o VPS s ID 123 
 +  * ''vps#*'' umožní volat všechny akce nad všemi VPS 
 +  * ''vps#*:vps_id=123'' všechny akce nad VPS s ID 123 
 +  * ''{vps,dataset}#{index,show}''  umožní vylistovat VPS a datasety a zobrazit údaje o jednom konkrétním
  
-=== Instalace závislostí ===+Scope může obsahovat globy pro název resource a akce. Akce je od resource oddělena křížkem (''#''). Volitelné ID objektů se píšou za dvojtečkou ('':'') a nemohou obsahovat globy, musí být přesně. Každý token může mít více nastavených scopes, oddělují se mezerou. Pro udělení přístupu musí aspoň jedno nastavené scope platit pro volanou akci v API.
  
-<code bash> +===== Instalace klienta ===== 
-sudo apt-get install ruby ruby-dev make g++ libssl-dev libncurses-dev +[[https://github.com/vpsfreecz/vpsfree-client|Klient pro Ruby]] obsahuje CLI 
-</code> +(rozhraní pro příkazovou řádku) a knihovnu pro použití v Ruby skriptech. 
- +Pro správnou funkci vyžaduje Ruby >= 2.7, nainstalované hlavičkové soubory 
-=== Instalace vpsfree-client ===+Ruby a ncurses (většinou balíčky s příponou ''-dev'' či ''-devel''). 
 +Poté klienta nainstalujeme pomocí Ruby gems:
  
 <code bash> <code bash>
-sudo gem install vpsfree-client+gem install vpsfree-client
 </code> </code>
  
 +Konkrétní postupy instalace podle platformy:
  
-====Instalace na Centos 7==== +  * Linux 
- +    * [[navody:vps:api:arch|Arch Linux]] 
-Zdrojový kod klienta lze najít [[https://github.com/vpsfreecz/vpsfree-client|zde]] +    * [[navody:vps:api:centos|CentOS]] 
- +    * [[navody:vps:api:ubuntu|Ubuntu 20.04]] 
-vpsfree-client vyžaduje ruby >–2.30 +  * [[navody:vps:api:macos|macOS]] 
- +  * [[navody:vps:api:windows|Windows]]
-Ruby ve verzi nižší než [[https://www.ruby-lang.org/en/downloads/branches/|2.5 jsou EOL]] +
- +
-Aktuální Ruby je možné nainstalovat pomocí [[ https://linuxize.com/post/how-to-install-ruby-on-centos-7/|tohoto návodu]]. +
- +
-Například: +
-<code> +
-yum install -y openssl-devel readline-devel zlib-devel +
-/build/vpsfree-client:curl -sL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-installer | bash - +
-# následně je zapotřebí přidat rbenv do PATH a provést trochu magie(snippet z .bashrc): +
-export PATH="${PATH}:/root/.rbenv/bin" +
-if [ -d '/root/.rbenv' ]; then +
-  eval "$(rbenv init -)" +
-fi +
-/build/vpsfree-client:rbenv install 2.5.7 +
-/build/vpsfree-client:rbenv global 2.5.7 +
-#projistotu spustte nový bash který uvidí novou verzi ruby +
-/build/vpsfree-client:bash +
-#proveďte instalaci +
-/build/vpsfree-client:gem install vpsfree-client +
-#otestujeme +
-/build/vpsfree-client:which vpsfreectl +
-/root/.rbenv/shims/vpsfreectl +
-/build/vpsfree-client:vpsfreectl -h +
-Usage: /root/.rbenv/versions/2.5.7/bin/vpsfreectl [options] <resource> <action> [objects ids] [-- [parameters]] +
-... +
-</code> +
-=============== +
-====Instalace CLI na Linux distribucích založených na Arch Linux==== +
-Testováno na [[https://manjaro.org/download/xfce/|Manjaro 18.04 Xfce]]: +
- +
-<code bash> +
-sudo pacman -Syu ruby make gcc +
-gem install vpsfree-client # nainstalujeme vpsfree-client (nepoužívejte tady SUDO install!) +
-</code> +
- +
-Přidáme PATH k nainstalovaným gems do ''~./bashrc''. +
- +
-<code bash> +
-sudo nano ~/.bashrc +
-</code> +
- +
-Na konec souboru přidáme: +
- +
-<code bash> +
-if command -v ruby &>/dev/null && command -v gem &>/dev/null; then +
-    PATH="$(ruby -r rubygems -e 'puts Gem.user_dir')/bin:$PATH" +
-fi +
-</code> +
- +
-Restartujeme shell ''exec $SHELL'' nebo počítač. Otestujeme funkčnost CLI, třeba příkazem: +
-<code bash> +
-vpsfreectl ip_traffic top +
-</code> +
- +
-Výše uvedené příkazy nefungují na distribucích založených na Debian/Ubuntu a jiných. +
- +
-==== macOS ==== +
- +
-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 bash> +
-$ brew install openssl +
-$ sudo gem install eventmachine -- --with-opt-include="/usr/local/opt/openssl/" +
-</code> +
- +
-Nainstalovat jej lze pomocí ruby gems: +
- +
-<code bash> +
-$ sudo gem install vpsfree-client +
-</code> +
- +
-<note> +
-gem vypíše PATH pod kterým lze najít nainstalovaný balíček +
-<code bash> +
-WARNING:  You don\'t have /home/user/.gem/ruby/2.5.0/bin in your PATH, +
-   gem executables will not run. +
- +
-</code> +
-</note> +
- +
-==== Windows ==== +
-Instalace ve Windows 10 využitím Ubuntu Linux subsystem: +
- +
-  - 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.1 ruby2.1-dev libssl-dev make g++ +
-</code> +
- +
-=== Quick & Dirty fix pro nastavení ruby2.1 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.1 /usr/bin/ruby +
-sudo ln -s /usr/bin/gem2.1 /usr/bin/gem +
-sudo ln -s /usr/bin/irb2.1 /usr/bin/irb +
-sudo ln -s /usr/bin/rdoc2.1 /usr/bin/rdoc +
-sudo ln -s /usr/bin/erb2.1 /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 Po instalaci by v ''$PATH'' měl být k dispozici ''vpsfreectl''. Pokud tomu tak
Řádek 217: Řádek 115:
  
 <code bash> <code bash>
-$ PATH="$PATH:/home/user/.gem/ruby/2.0.0/bin"+$ PATH="$PATH:/home/user/.gem/ruby/2.7.0/bin"
 </code> </code>
  
-==== Použití CLI ====+===== Použití CLI =====
  
 <code> <code>
Řádek 375: Řádek 273:
         --user USER                  User name         --user USER                  User name
         --password PASSWORD          Password         --password PASSWORD          Password
 +        --scope [SCOPE]              Scope
         --token TOKEN                Token         --token TOKEN                Token
         --token-lifetime LIFETIME    Token lifetime, defaults to renewable_auto         --token-lifetime LIFETIME    Token lifetime, defaults to renewable_auto
Řádek 419: Řádek 318:
 přístupem k ''~/.haveapi-client.yml'' může token získat a použít. přístupem k ''~/.haveapi-client.yml'' může token získat a použít.
 </note> </note>
 +
 +Při vytváření tokenu můžeme specifikovat scope:
 +<code bash>
 +$ vpsfreectl --auth token --scope 'vps#*:vps_id=123' --save vps show 123
 +</code>
 +
 +Příkaz výše vytvoří autentizační token, který bude omezen na volání akcí nad resource ''vps'' s ID 123.
  
 ==== Akce a parametry ==== ==== Akce a parametry ====
navody/vps/api.1639051720.txt.gz · Poslední úprava: 2021/12/09 12:08 autor: Aither

Nástroje pro stránku

Kromě míst, kde je explicitně uvedeno jinak, je obsah této wiki licencován pod následující licencí: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki