Rozdíly

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

--- navody:vps:api [2017/12/28 12:59] – upraven příkaz instalace gem install vpsfree-client - od verze 10.12 je třeba spouštět příkaz se sudo h00ked
+++ navody:vps:api [2026/07/12 12:50] (aktuální) – Publish reviewed KB release aither
@@ Řádek 2: / Řádek 2: @@
 ====== API ======
-Naše API běží na adrese https://api.vpsfree.cz. Pomocí API lze vykonat většinu
+Naše API běží na adrese https://api.vpsfree.cz. Pomocí API lze vykonat vše
-akcí, stejně jako z webového rozhraní. V API aktuálně není zahrnuta pouze
+co jde naklikat ve webovém rozhraní, a více. Ve skutečnosti webové rozhraní
-správa uživatelských profilů (adresa, e-mail, apod.).
+běžící na https://vpsadmin.vpsfree.cz pro každý úkon volá API.
-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
+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/v4.1/.
+parametrů je k vidění na https://api.vpsfree.cz/.
-Bez přihlášení se zobrazuje seznam všech objektů, 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
 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
@@ Řádek 26: / Řádek 23: @@
   * Ruby - https://github.com/vpsfreecz/vpsfree-client
-  * PHP - https://github.com/vpsfreecz/haveapi-client-php
+  * PHP - https://github.com/vpsfreecz/haveapi/tree/master/clients/php
-  * JavaScript - https://github.com/vpsfreecz/haveapi-client-js
+  * JavaScript - https://github.com/vpsfreecz/haveapi/tree/master/clients/js
-  * Webové rozhraní z HaveAPI - https://github.com/vpsfreecz/haveapi-webui
+  * Go - https://github.com/vpsfreecz/haveapi/tree/master/clients/go
-  * Souborový systém založený na FUSE - https://github.com/vpsfreecz/haveapi-fs
+  * Webové rozhraní z HaveAPI - https://github.com/vpsfreecz/haveapi-webui (zastaralé)
+  * 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
@@ Řádek 39: / Řádek 37: @@
 [[https://api.vpsfree.cz/doc/protocol.md|dokumentaci]].
-===== Autentizace =====
+**poznámka** Pokud API vpsfree vrací http kód 500, ujistěte se, že váš REST klient posílá http hlavičku `User-Agent: x"`, která nesmí být prázdným řetězcem. Nejspíš jsou povinné i hlavičky `Accept: application/json` a `"Content-Type: application/json`. Většina http rest knihoven hlavičku `User-Agent` přidá automaticky, ale některé to nedělají.
-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
+===== Autentizace =====
-  * renewable_manual - platnost tokenu lze manuálně prodloužit
+API podporuje dva způsoby autentizace:
-  * 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.
+  * [[#http_basic|HTTP Basic]]
+  * [[#tokeny|Pomocí tokenů]]
-===== CLI =====
+Konkrétní ukázky autentizace pro podporované programovací jazyky a CLI najdete
-[[https://github.com/vpsfreecz/vpsfree-client|Klient pro Ruby]] obsahuje i CLI.
+v [[https://api.vpsfree.cz/v6.0/#auth|dokumentaci API]].
-Pro správnou funkci vyžaduje Ruby >= 2.0 a nainstalované hlavičkové soubory
-Ruby, OpenSSL a ncurses (většinou balíčky s příponou ''-dev'' či ''-devel'').
-<note>
+==== HTTP Basic ====
-Na OS X je nutné nainstalovat OpenSSL přes [[http://brew.sh/|Homebrew]] a až
+S každým požadavkem na API se musí zaslat jméno a heslo v HTTP hlavičce "Authorization".
-poté se dá nainstalovat EventMachine (gem, jenž klient vyžaduje).
+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í.
-<code bash>
+==== Tokeny ====
-$ brew install openssl
+Klient nejprve požádá o vytvoření tokenu, k tomu potřebuje jméno, heslo a připadně i TOTP.
-$ sudo gem install eventmachine -- --with-opt-include="/usr/local/opt/openssl/"
+Jakmile klient dostane token, může jméno a heslo zapomenout a dále se autentizuje
-</code>
+získaným tokenem.
-</note>
-Nainstalovat jej lze pomocí ruby gems:
+Tokeny mohou být několika typů s různě dlouhou životností:
-<code bash>
+  * //fixed// - platnost tokenu je pevně dána
-$ sudo gem install vpsfree-client
+  * //renewable_manual// - platnost tokenu lze manuálně prodloužit
-</code>
+  * //renewable_auto// - platnost tokenu je prodloužena při každém požadavku
+  * //permanent// - token je platný napořád, resp. dokud není smazán
-==== Instalace ve Windows 10 využitím Ubuntu Linux subsystem ====
+Typ tokenu a časový interval, o který se prodlužuje, si volí klient.
-=== Instalace Ubuntu (Linux subsystemu Windows 10) ===
+===== Scopes =====
+U autentizačních tokenů si můžeme zvolit, jaké akce bude token mít k dispozici.
+To se může hodit u tokenů s dlouhou nebo permanentní platností. Každá akce
+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.
-  - ve Windows 10 povolit developer mode, nechat nainstalovat
+Ukázky možných scopes:
-  - 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í ===
+  * ''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
-<code bash>
+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.
-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 ===
+===== Instalace klienta =====
+[[https://github.com/vpsfreecz/vpsfree-client|Klient pro Ruby]] obsahuje CLI
+(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
+Ruby a ncurses (většinou balíčky s příponou ''-dev'' či ''-devel'').
+Poté klienta nainstalujeme pomocí Ruby gems:
 <code bash>
-sudo rm /usr/bin/ruby /usr/bin/gem /usr/bin/irb /usr/bin/rdoc /usr/bin/erb
+gem install vpsfree-client
-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
+Konkrétní postupy instalace podle platformy:
-=== Instalace vpsfree-client ===
-<code bash>
-sudo gem install vpsfree-client
-</code>
-----
+  * Linux
+    * [[navody:vps:api:arch|Arch Linux]]
+    * [[navody:vps:api:centos|CentOS]]
+    * [[navody:vps:api:ubuntu|Ubuntu 20.04]]
+  * [[navody:vps:api:macos|macOS]]
+  * [[navody:vps:api:windows|Windows]]
 Po instalaci by v ''$PATH'' měl být k dispozici ''vpsfreectl''. Pokud tomu tak
@@ Řádek 131: / Řádek 119: @@
 <code bash>
-$ PATH="$PATH:/home/user/.gem/ruby/2.0.0/bin"
+$ PATH="$PATH:/home/user/.gem/ruby/2.7.0/bin"
 </code>
-==== Použití ====
+===== Použití CLI =====
 <code>
@@ Řádek 178: / Řádek 166: @@
 Available resources:
-auth_token
 cluster
 cluster_resource
+cluster_resource_package
+cluster_resource_package.item
 dataset
 dataset.snapshot
@@ Řádek 190: / Řádek 179: @@
 environment.config_chain
 environment.dataset_plan
+host_ip_address
 integrity_check
 integrity_fact
 integrity_object
 ip_address
-ip_range
 ip_traffic
 ip_traffic_monitor
@@ Řádek 207: / Řádek 196: @@
 migration_plan.vps_migration
 network
+network_interface
 node
 node.status
@@ Řádek 212: / Řádek 202: @@
 os_template
 pool
+session_token
 snapshot_download
+system_config
 transaction
 transaction_chain
@@ Řádek 219: / Řádek 211: @@
 user.cluster_resource
 user.public_key
+user.mail_role_recipient
+user.mail_template_recipient
 user.state_log
+user_cluster_resource_package
+user_cluster_resource_package.item
+user_namespace
+user_namespace_map
+user_namespace_map.entry
 user_session
 vps
@@ Řádek 225: / Řádek 224: @@
 vps.config
 vps.feature
-vps.ip_address
 vps.mount
 vps.outage_window
@@ Řádek 231: / Řádek 229: @@
 vps.status
 vps_config
+monitored_event
+monitored_event.log
+outage
+outage.entity
+outage.handler
+outage_update
+user_outage
+vps_outage
+vps_outage_mount
+help_box
+news_log
+incoming_payment
+payment_stats
+user_account
+user_payment
+user_request
+user_request.registration
+user_request.change
 action_state
 </code>
@@ Řádek 259: / Řádek 275: @@
     -a, --auth METHOD                Authentication method
     -s, --save                       Save credentials to config file for later
-        --username USER              User name
+        --user USER                  User name
         --password PASSWORD          Password
+        --scope [SCOPE]              Scope
         --token TOKEN                Token
         --token-lifetime LIFETIME    Token lifetime, defaults to renewable_auto
@@ Řádek 305: / Řádek 322: @@
 přístupem k ''~/.haveapi-client.yml'' může token získat a použít.
 </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 ====
@@ Řádek 462: / Řádek 486: @@
 se hned ukončit a nečekat. Informace o dokončení akce je však důležitá, neboť
 nad jedním objektem (tedy třeba VPS) lze vykonávat v jednom čase jen jednu
-akci, ostatní skončí s chybou "Resource is locked".
+akci, ostatní skončí s chybou „Zdroj je uzamčen. Zkuste to prosím později.“
 Ve výchozím stavu ''vpsfreectl'' blokuje:
@@ Řádek 677: / Řádek 701: @@
 aither
 </maintainers>

Znalostní báze

Uživatelské nástroje

Nástroje pro tento web

Rozdíly

Nástroje pro stránku