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:
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 [2024/01/02 21:06] – [Instalace klienta] Nepotrebujeme openssl aithernavody:vps:api [2026/11/01 19:49] (aktuální) – Přehled klientů a příklady pro PHP, Python, JavaScript, TypeScript, Go a Rust 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 16: Řádek 16:
  
 ===== Práce s API ===== ===== Práce s API =====
-API je postaveno na námi vyvinutém frameworku +API používá framework [[https://github.com/vpsfreecz/haveapi|HaveAPI]]. 
-[[https://github.com/vpsfreecz/haveapi|HaveAPI]], které vytváří +Jeho [[https://github.com/vpsfreecz/haveapi#what-is-a-self-describing-api|popis]] 
-[[https://github.com/vpsfreecz/haveapi#what-is-a-self-describing-api|samodokumentující]] +obsahuje dostupné zdroje, akce a parametry.
-se API, což znamená, že lze využít předpřipravené generické +
-klienty:+
  
-  * Ruby - https://github.com/vpsfreecz/vpsfree-client +Pro práci s API můžeš použít tyto klienty:
-  * PHP - https://github.com/vpsfreecz/haveapi/tree/master/clients/php +
-  * 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 (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 +  * [[#instalace_klienta|CLI vpsfreectl]] a [[#klient_pro_ruby|knihovna pro Ruby]] z balíčku ''vpsfree-client'' 
-předá URL k API, poté si sám stáhne dokumentaci a podle ní se nastaví.+  * [[#klient_pro_php|PHP]] 
 +  * [[#klient_pro_python|Python]] 
 +  * [[#dynamicky_klient_haveapi_pro_javascript_a_typescript|Dynamický klient HaveAPI pro JavaScript a TypeScript]] 
 +  * [[#klient_pro_go|Go]] 
 +  * [[#generovany_klient_pro_vpsadmin_v_typescriptu|Generovaný klient pro vpsAdmin v TypeScriptu]] 
 +  * [[#klient_pro_rust|Rust]]
  
 API je [[wp>Representational state transfer|RESTful]], takže pro jednoduché API je [[wp>Representational state transfer|RESTful]], takže pro jednoduché
Řádek 43: Řádek 41:
   * [[#tokeny|Pomocí tokenů]]   * [[#tokeny|Pomocí tokenů]]
  
-Konkrétní ukázky autentizace pro podporované programovací jazyky a CLI najdete +Ukázky autentizace pro podporované programovací jazyky a CLI najdeš 
-v [[https://api.vpsfree.cz/v6.0/#auth|dokumentaci API]].+v [[https://api.vpsfree.cz/|dokumentaci API]].
  
 ==== HTTP Basic ==== ==== HTTP Basic ====
Řádek 62: Řádek 60:
   * //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+  * //permanent// - 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.
 +
 +Autentizace tokenem musí být pro tvůj účet povolená. Ukázky níže se přihlašují
 +uživatelským jménem a heslem. Pokud přihlášení vyžaduje také kód TOTP nebo změnu
 +hesla, použij přihlašovací postup z dokumentace klienta nebo existující token.
  
 ===== Scopes ===== ===== Scopes =====
Řádek 85: Řádek 87:
  
 ===== Instalace klienta ===== ===== Instalace klienta =====
-[[https://github.com/vpsfreecz/vpsfree-client|Klient pro Ruby]] obsahuje CLI +Balíček [[https://github.com/vpsfreecz/vpsfree-client|vpsfree-client]] obsahuje 
-(rozhraní pro příkazovou řádku) a knihovnu pro použití v Ruby skriptech. +příkaz ''vpsfreectl'' pro práci z příkazové řádky i knihovnu pro Ruby skripty. 
-Pro správnou funkci vyžaduje Ruby >= 2.7, nainstalované hlavičkové soubory +Potřebuješ Ruby, jeho hlavičkové soubory a ncurses (většinou balíčky s příponou 
-Ruby a ncurses (většinou balíčky s příponou ''-dev'' či ''-devel'').+''-dev'' či ''-devel''). Požadavky na závislosti najdeš na 
 +[[https://rubygems.org/gems/vpsfree-client|stránce balíčku]].
 Poté klienta nainstalujeme pomocí Ruby gems: Poté klienta nainstalujeme pomocí Ruby gems:
  
Řádek 100: Řádek 103:
     * [[navody:vps:api:arch|Arch Linux]]     * [[navody:vps:api:arch|Arch Linux]]
     * [[navody:vps:api:centos|CentOS]]     * [[navody:vps:api:centos|CentOS]]
-    * [[navody:vps:api:ubuntu|Ubuntu 20.04]]+    * [[navody:vps:api:ubuntu|Ubuntu]]
   * [[navody:vps:api:macos|macOS]]   * [[navody:vps:api:macos|macOS]]
   * [[navody:vps:api:windows|Windows]]   * [[navody:vps:api:windows|Windows]]
Řádek 115: Řádek 118:
  
 <code bash> <code bash>
-$ PATH="$PATH:/home/user/.gem/ruby/2.7.0/bin"+$ export PATH="$PATH:$(ruby -r rubygems -e 'puts Gem.bindir')"
 </code> </code>
  
Řádek 482: Řádek 485:
 se hned ukončit a nečekat. Informace o dokončení akce je však důležitá, neboť 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 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: Ve výchozím stavu ''vpsfreectl'' blokuje:
Řádek 546: Řádek 549:
 </code> </code>
  
-===== Souborový systém ====== +===== Klient pro Ruby =====
-''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 bash> +Knihovnu ze stejného balíčku ''vpsfree-client'' můžeš použít ve vlastních skriptech. 
-$ gem install haveapi-fs +Ukázka získá [[#tokeny|token API]] pomocí uživatelského jména a hesla do vpsAdminu 
-</code>+a pak vypíše tvé VPS. Místo ''USERNAME'' a ''PASSWORD'' doplň své přihlašovací 
 +údaje. Pokud už token máš, nahraď přihlašovací kód zakomentovanou alternativou 
 +a doplň ho místo ''TOKEN'':
  
-==== Použití ==== +<code ruby> 
-Použití ''haveapi-fs'' je podrobně popsáno v +require 'vpsfree/client'
-[[https://github.com/vpsfreecz/haveapi-fs#usage|README.md]], zde jen ve +
-zkratce.+
  
-<code> +api = VpsFree::Client.new 
-$ haveapi-fs https://api.vpsfree.cz /mnt/api.vpsfree.cz +api.authenticate(:token, user: 'USERNAME', password: 'PASSWORD', 
-Username: mujlogin +                 lifetime: 'renewable_auto') 
-Password:+# Nebo předchozí přihlášení nahraď existujícím tokenem: 
 +# api.authenticate(:token, token: 'TOKEN')
  
-$ cd /mnt/api.vpsfree.cz +api.vps.list.each do |vps| 
-$ ls -1 +  puts "#{vps.id}: #{vps.hostname}" 
-auth_token +end
-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> </code>
  
-V každém adresáři se nachází soubory ''help.{html,txt,md,man}'', které popisují co +Další možnosti knihovny popisuje 
-aktuální adresář obsahuje. +[[https://github.com/vpsfreecz/vpsfree-client#client-library|README klienta]].
- +
-<code> +
-$ cat vps/5685/hostname  +
-moje-vps+
  
-$ echo lepsi-hostname > vps/5685/hostname +==== Ukázky použití ====
-$ echo 1 > vps/5685/save +
-$ cat vps/5685/actions/update/status  +
-1 +
-$ 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 Následují skripty demonstrují možnosti využití API. Tyto skripty lze
 spouštět odkudkoli -- manuálně, z cronu, apod. spouštět odkudkoli -- manuálně, z cronu, apod.
Řádek 631: Řádek 584:
 </note> </note>
  
-==== Každodenní stahování záloh VPS ====+=== Každodenní stahování záloh VPS ===
 <code ruby> <code ruby>
 #!/usr/bin/env ruby #!/usr/bin/env ruby
Řádek 638: Řádek 591:
  
 api = VpsFree::Client.new api = VpsFree::Client.new
-api.authenticate(:token, token: 'PUT YOUR TOKEN HERE')+api.authenticate(:token, user: 'USERNAME', password: 'PASSWORD', 
 +                 lifetime: 'renewable_auto') 
 +# Nebo předchozí přihlášení nahraď existujícím tokenem: 
 +# api.authenticate(:token, token: 'TOKEN')
  
 api.dataset.list(role: :hypervisor).each do |ds| api.dataset.list(role: :hypervisor).each do |ds|
Řádek 662: Řádek 618:
 </code> </code>
  
-==== Denní zálohování NASu s týdenní historií ====+=== Denní zálohování NASu s týdenní historií ===
 <code ruby> <code ruby>
 #!/usr/bin/env ruby #!/usr/bin/env ruby
Řádek 669: Řádek 625:
  
 api = VpsFree::Client.new api = VpsFree::Client.new
-api.authenticate(:token, token: 'PUT YOUR TOKEN HERE')+api.authenticate(:token, user: 'USERNAME', password: 'PASSWORD', 
 +                 lifetime: 'renewable_auto') 
 +# Nebo předchozí přihlášení nahraď existujícím tokenem: 
 +# api.authenticate(:token, token: 'TOKEN')
  
 api.dataset.list(role: :primary).each do |ds| api.dataset.list(role: :primary).each do |ds|
Řádek 693: Řádek 652:
 end end
 </code> </code>
 +
 +===== Další klienti =====
 +
 +Každá ukázka získá [[#tokeny|token API]] pomocí uživatelského jména a hesla do
 +vpsAdminu a pak vypíše ID a hostname nejvýše 10 VPS. Místo ''USERNAME''
 +a ''PASSWORD'' doplň své přihlašovací údaje. Pokud už token máš, nahraď
 +přihlašovací kód zakomentovanou alternativou a doplň ho místo ''TOKEN''.
 +
 +==== Klient pro PHP ====
 +
 +[[https://github.com/vpsfreecz/haveapi/tree/master/clients/php|Klienta HaveAPI pro PHP]]
 +nainstaluj pomocí Composeru:
 +
 +<code bash>
 +composer require haveapi/client
 +</code>
 +
 +Ukázku ulož jako ''vps-list.php'' vedle adresáře ''vendor'' a spusť příkazem
 +''php vps-list.php'':
 +
 +<code php>
 +<?php
 +require __DIR__ . '/vendor/autoload.php';
 +
 +$api = new \HaveAPI\Client('https://api.vpsfree.cz');
 +$api->authenticate('token', ['user' => 'USERNAME', 'password' => 'PASSWORD']);
 +// Nebo předchozí přihlášení nahraď existujícím tokenem:
 +// $api->authenticate('token', ['token' => 'TOKEN']);
 +
 +foreach ($api->vps->list(['limit' => 10]) as $vps) {
 +    echo $vps->id . ': ' . $vps->hostname . PHP_EOL;
 +}
 +</code>
 +
 +Další akce a zpracování chyb popisuje
 +[[https://github.com/vpsfreecz/haveapi/tree/master/clients/php#usage|README klienta]].
 +
 +==== Klient pro Python ====
 +
 +Balíček [[https://pypi.org/project/haveapi-client/|haveapi-client]] nainstaluj pomocí pip:
 +
 +<code bash>
 +python -m pip install haveapi-client
 +</code>
 +
 +Ukázku ulož jako ''vps-list.py'' a spusť příkazem ''python vps-list.py'':
 +
 +<code python>
 +from haveapi_client import Authenticated, Client, TokenAuth
 +
 +with Client("https://api.vpsfree.cz") as api:
 +    login = api.begin_token_login({
 +        "user": "USERNAME",
 +        "password": "PASSWORD",
 +        "lifetime": "renewable_auto",
 +    })
 +    if not isinstance(login, Authenticated):
 +        raise RuntimeError("Přihlášení vyžaduje další krok")
 +    # Nebo předchozí blok přihlášení nahraď existujícím tokenem:
 +    # api.set_auth(TokenAuth("TOKEN"))
 +
 +    result = api.vps.list(limit=10)
 +    for vps in result.data:
 +        print(vps["id"], vps["hostname"])
 +</code>
 +
 +[[https://github.com/vpsfreecz/haveapi/tree/master/clients/python|README klienta]]
 +popisuje také asynchronní volání s ''AsyncClient''.
 +
 +==== Dynamický klient HaveAPI pro JavaScript a TypeScript ====
 +
 +Oba jazyky používají stejný balíček z npm, který obsahuje i deklarace typů pro TypeScript:
 +
 +<code bash>
 +npm install haveapi-client
 +</code>
 +
 +Ukázka funguje v JavaScriptu i TypeScriptu. Pro spuštění v Node.js ji ulož jako
 +''vps-list.mjs'' a použij příkaz ''node vps-list.mjs'':
 +
 +<code javascript>
 +import { AsyncClient } from "haveapi-client";
 +
 +async function main() {
 +  const api = new AsyncClient("https://api.vpsfree.cz");
 +  await api.authenticate("token", { user: "USERNAME", password: "PASSWORD" });
 +  // Nebo předchozí přihlášení nahraď existujícím tokenem:
 +  // await api.authenticate("token", { token: "TOKEN" });
 +  const result = await api.resource("vps").action("list")({
 +    params: { limit: 10 },
 +  });
 +  const vpses = result.response.data;
 +  if (Array.isArray(vpses)) {
 +    for (const vps of vpses) {
 +      console.log(vps.id, vps.hostname);
 +    }
 +  }
 +}
 +
 +main().catch(() => console.error("Požadavek na API selhal."));
 +</code>
 +
 +Další akce a použití v prohlížeči najdeš v
 +[[https://github.com/vpsfreecz/haveapi/tree/master/clients/js|README klienta]].
 +
 +==== Klient pro Go ====
 +
 +[[https://github.com/vpsfreecz/vpsadmin-go-client|Klienta pro vpsAdmin v Go]]
 +přidej do svého Go modulu:
 +
 +<code bash>
 +go get github.com/vpsfreecz/vpsadmin-go-client/client
 +</code>
 +
 +Ukázku ulož jako ''main.go'' a spusť příkazem ''go run .'':
 +
 +<code go>
 +package main
 +
 +import (
 + "fmt"
 + "log"
 +
 + "github.com/vpsfreecz/vpsadmin-go-client/client"
 +)
 +
 +func main() {
 + api := client.New("https://api.vpsfree.cz")
 + if err := api.SetNewTokenAuth(&client.TokenAuthOptions{
 + User:     "USERNAME",
 + Password: "PASSWORD",
 + }); err != nil {
 + log.Fatal(err)
 + }
 + // Nebo předchozí blok přihlášení nahraď existujícím tokenem:
 + // api.SetExistingTokenAuth("TOKEN")
 +
 + action := api.Vps.Index.Prepare()
 + action.NewInput().SetLimit(10)
 + response, err := action.Call()
 + if err != nil {
 + log.Fatal(err)
 + }
 + if !response.Status {
 + log.Fatalf("%s: %v", response.Message, response.Errors)
 + }
 +
 + for _, vps := range response.Output {
 + fmt.Println(vps.Id, vps.Hostname)
 + }
 +}
 +</code>
 +
 +Další akce a parametry najdeš v
 +[[https://github.com/vpsfreecz/vpsadmin-go-client#usage|README klienta]].
 +
 +==== Generovaný klient pro vpsAdmin v TypeScriptu ====
 +
 +[[https://github.com/vpsfreecz/vpsadmin-typescript-client|Klient pro vpsAdmin v TypeScriptu]]
 +poskytuje typované metody pro zdroje a akce vpsAdminu. Nainstaluj ho pomocí npm,
 +které přidá i jeho závislost ''haveapi-client'':
 +
 +<code bash>
 +npm install vpsadmin-typescript-client
 +</code>
 +
 +Ukázka funguje v JavaScriptu i TypeScriptu. Pro spuštění v Node.js ji ulož jako
 +''vps-list.mjs'' a použij příkaz ''node vps-list.mjs''.
 +U tohoto klienta použij základní adresu ''https://api.vpsfree.cz/v7.0'':
 +
 +<code javascript>
 +import { AsyncClient } from "haveapi-client";
 +import { createHaveApiExecutor, createVpsAdminClient } from "vpsadmin-typescript-client";
 +
 +async function main() {
 +  const runtime = new AsyncClient("https://api.vpsfree.cz/v7.0");
 +  await runtime.authenticate("token", { user: "USERNAME", password: "PASSWORD" });
 +  // Nebo předchozí přihlášení nahraď existujícím tokenem:
 +  // await runtime.authenticate("token", { token: "TOKEN" });
 +  const api = createVpsAdminClient({ execute: createHaveApiExecutor(runtime) });
 +  const page = await api.vps.index({ params: { limit: 10 } });
 +  for (const vps of page.data) {
 +    console.log(vps.id, vps.hostname);
 +  }
 +}
 +
 +main().catch(() => console.error("Požadavek na API selhal."));
 +</code>
 +
 +Další akce a typy popisuje
 +[[https://github.com/vpsfreecz/vpsadmin-typescript-client#readme|README klienta]].
 +
 +==== Klient pro Rust ====
 +
 +Do svého projektu v Rustu přidej balíček
 +[[https://crates.io/crates/vpsadmin-client|vpsadmin-client]]. Ukázka používá
 +synchronní volání, proto zapni podporu ''blocking'':
 +
 +<code bash>
 +cargo add vpsadmin-client --features blocking
 +</code>
 +
 +Ukázku ulož jako ''src/main.rs'' a spusť příkazem ''cargo run'':
 +
 +<code rust>
 +use vpsadmin_client::{blocking::Client, TokenStep};
 +
 +fn main() -> Result<(), Box<dyn std::error::Error>> {
 +    let login = Client::builder("https://api.vpsfree.cz").build()?;
 +    let response = login.authentication__token__token().request()
 +        .user("USERNAME")
 +        .password("PASSWORD")
 +        .lifetime("renewable_auto")
 +        .send()?;
 +    let TokenStep::Complete { token } = response.output.token_step()? else {
 +        return Err("Přihlášení vyžaduje další krok".into());
 +    };
 +    let api = Client::builder("https://api.vpsfree.cz")
 +        .token(token.expose_secret())
 +        .build()?;
 +    // Nebo předchozí přihlášení a vytvoření klienta nahraď existujícím tokenem:
 +    // let api = Client::builder("https://api.vpsfree.cz").token("TOKEN").build()?;
 +
 +    let response = api.vps().index().limit(10).send()?;
 +    for vps in response.output {
 +        if let (Some(id), Some(hostname)) = (vps.id, vps.hostname) {
 +            println!("{} {}", id, hostname);
 +        }
 +    }
 +    Ok(())
 +}
 +</code>
 +
 +Další akce, asynchronní volání a požadavky na Rust najdeš v
 +[[https://github.com/vpsfreecz/vpsadmin-rust-client#readme|README klienta]].
  
 <maintainers hidden> <maintainers hidden>
navody/vps/api.1704229597.txt.gz · Poslední úprava: 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