Rozdíly

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

--- navody:vps:api [2022/01/26 10:17] – Postupy instalace rozděleny do podstránek Aither
+++ navody: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, 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
@@ Řádek 26: / Řádek 26: @@
   * JavaScript - https://github.com/vpsfreecz/haveapi/tree/master/clients/js
   * 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
@@ Řádek 38: / Řádek 38: @@
 ===== 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
 získaným tokenem.
@@ Řádek 50: / Řádek 59: @@
 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.
+===== 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.
+Ukázky možných scopes:
+  * ''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
+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.
 ===== 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 a nainstalované hlavičkové soubory
+Pro správnou funkci vyžaduje Ruby >= 2.7, nainstalované hlavičkové soubory
-Ruby, OpenSSL a ncurses (většinou balíčky s příponou ''-dev'' či ''-devel'').
+Ruby a ncurses (většinou balíčky s příponou ''-dev'' či ''-devel'').
 Poté klienta nainstalujeme pomocí Ruby gems:
@@ Řádek 246: / Řádek 273: @@
         --user USER                  User name
         --password PASSWORD          Password
+        --scope [SCOPE]              Scope
         --token TOKEN                Token
         --token-lifetime LIFETIME    Token lifetime, defaults to renewable_auto
@@ Řádek 290: / Řádek 318: @@
 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 ====

Znalostní báze

Uživatelské nástroje

Nástroje pro tento web

Rozdíly

Nástroje pro stránku