Vai al contenuto

Panoramica

Cloud Server Shared CPU è il servizio cloud on-demand ideale per test, sviluppo, staging e per chi ha bisogno di creare e distruggere macchine cloud con fatturazione a consumo, in modo rapido e con costi ottimizzati.

In questa sezione vengono approfondite le funzionalità Rest API dei servizi:

  • Cloud Server Shared CPU
  • Cloud Server High Memory
  • Cloud Server GPU

Crea Il tuo primo Server via API

Creare un Server virtuale via API è molto semplice e in questa pagina sono presenti tutte le informazioni necessarie per istanziare velocemente un Server virtuale

In questa guida viene utilizzato il software a riga di comando curl per eseguire le nostre chiamate ma qualsiasi client HTTP può sostituirlo senza problemi come ad esempio Postman o Bruno

Eseguire il login

Come prima operazione è necessario eseguire il login sui nostri servizi e generare un token JWT di accesso. La spiegazione di cos'è un token JWT è esterna a questa guida e non è necessaria per l'utilizzo dei nostri servizi. Può essere immaginato come una chiave che identifica chi l'ha generata e chi la utilizza

Per generarlo dobbiamo eseguire la seguente richiesta:

curl -X POST https://api.seeweb.it/ecs/v2/login \
  -H 'Content-Type: application/json' \
  -d  '{
  "username": "*il tuo nome utente*",
  "password": "*la tua password*"
}'

La risposta se le credenziali, sarà simile alla seguente:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtc2ciOiJXcm9uZyBQbGFjZSBkdWRlPyJ9.vBb9pIUYaxiGtO-7HY6hzBXH-q7L0GJS8stz2VYqb90",
  "expire": 1728560902,
  "status": "ok"
}

Il token presente nel corpo della risposta è appunto il Token JWT dell'utente e il campo expire indica la sua scadenza

In caso si voglia sapere in che momento il token non sarà più valido è possibile copiare il valore di expire e inserirlo sul sito Unix Timestamp Converter

O semplicemente usare il seguente Calcolatore

->

Info

Per altre informazioni sulla gestione degli utenti è possibile consultare Account

È anche possibile utilizzare gli API-Token per eseguire l'autenticazione ai nostri servizi, per far ciò consulta API Token

Creare un Server

Una volta ottenuto il Token JWT è possibile procedere alla creazione, per test creeremo un Server ubuntu di piccola taglia nel datacenter di Frosinone

Ottenere i Piani disponibili

Come primo passaggio è necessario visualizzare e identificare il piano di interesse e può essere fatto con la seguente richiesta:

curl -X GET https://api.seeweb.it/ecs/v2/plans \
   -H 'Authorization: Bearer *il tuo token*'

La risposta sarà simile alla seguente:

{
  "status": "ok",
  "plans": [
    {
      "id": 1,
      "name": "eCS1",
      "cpu": "1",
      "ram": "1024",
      "disk": "20",
      "gpu": "0",
      "gpu_label": null,
      "hourly_price": 0.019,
      "montly_price": 14.0,
      "windows": false,
      "host_type": "ECS",
      "available": true,
      "available_regions": [
        {
          "id": 2,
          "location": "it-mi2",
          "description": "Milano"
        },
        {
          "id": 3,
          "location": "it-fr2",
          "description": "Frosinone"
        },
        {
          "id": 6,
          "location": "ch-lug1",
          "description": "Lugano"
        },
        {
          "id": 7,
          "location": "bg-sof1",
          "description": "Sofia"
        }
      ]
    },
    {
      "id": 7,
      "name": "eCS2",
      "cpu": "2",
      "ram": "2048",
      "disk": "40",
      "gpu": "0",
      "gpu_label": null,
      "hourly_price": 0.032,
      "montly_price": 23.0,
      "windows": false,
      "host_type": "ECS",
      "available": true,
      "available_regions": [
        {
          "id": 2,
          "location": "it-mi2",
          "description": "Milano"
        },
        {
          "id": 3,
          "location": "it-fr2",
          "description": "Frosinone"
        },
        {
          "id": 6,
          "location": "ch-lug1",
          "description": "Lugano"
        }
      ]
    }
  ]
}

Ottenere le Regioni disponibili

Individuato il piano di interesse (nel nostro caso eCS1) possiamo procedere a verificare la disponibilità dello stesso nei vari datacenter.

curl -X POST https://api.seeweb.it/ecs/v2/regions/availables
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer *il tuo token*'                   
  -d '{
  "plan": "eCS1"
  }'

La risposta sarà simile alla seguente:

{
  "status": "ok",
  "regions": [
    [
      "ch-lug1",
      "it-fr2",
      "it-mi2",
      "bg-sof1"
    ]
  ]
}

È quindi possibile riscontrare che il piano 'eCS1' è attivabile nel datacenter denominato 'it-fr2' situato in italia a Frosinone.

Ottenere gli OS disponibili

Successivamente è necessario identificare un sistema operativo di interesse:

curl -X POST https://api.seeweb.it/ecs/v2/images/basics
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer *il tuo token*'

La risposta sarà simile alla seguente:

{
  "status": "ok",
  "images": [
    {
      "id": 408,
      "name": "debian-9",
      "creation_date": "2019-10-02T16:48:18+00:00",
      "active_flag": true,
      "status": "CD",
      "uuid": "a1fa433a-ef1a-4b09-8571-514474847495",
      "description": "Debian Linux 9",
      "notes": "Debian Linux distribution",
      "public": true,
      "cloud_image": false,
      "so_base": "debian",
      "api_version": "v4",
      "version": "9"
    },
    {
      "id": 409,
      "name": "ubuntu-1604",
      "creation_date": "2019-10-02T16:48:18+00:00",
      "active_flag": true,
      "status": "CD",
      "uuid": "87098cfe-9e2c-4020-acd3-c91e46fe46a9",
      "description": "Ubuntu Linux 16.04 LTS",
      "notes": "Ubuntu Linux distribution",
      "public": true,
      "cloud_image": false,
      "so_base": "ubuntu",
      "api_version": "v4",
      "version": "1604"
    },
        {
      "id": 509,
      "name": "ubuntu-2204",
      "creation_date": "2022-09-02T12:38:46+00:00",
      "active_flag": true,
      "status": "CD",
      "uuid": "2d41e9c4-280d-423b-8110-9d14173f601c",
      "description": "Ubuntu Linux 22.04 LTS",
      "notes": "Ubuntu Linux 22.04 LTS",
      "public": true,
      "cloud_image": false,
      "so_base": "ubuntu",
      "api_version": "v4",
      "version": "2204"
    },

    {
      "id": 411,
      "name": "windows-2012r2",
      "creation_date": "2019-10-02T16:48:18+00:00",
      "active_flag": true,
      "status": "CD",
      "uuid": "618c4587-812e-4e9c-bb1c-c7976f671477",
      "description": "Windows Server 2012 R2",
      "notes": "Windows Server 2012 R2 Standard Edition",
      "public": true,
      "cloud_image": false,
      "so_base": "windows",
      "api_version": "v4",
      "version": "2012"
    }
  ]
}

In caso si voglia utilizzare il sistema operativo 'Ubuntu Linux 22.04 LTS' è necessario il codice 'ubuntu-2204'

Creare un nuovo Server

Come ultimo passaggio si può procedere alla creazione:

curl -X POST https://api.seeweb.it/ecs/v2/servers
  -H 'Content-Type: application/json'
  -H 'Authorization: Bearer *il tuo token*'                   
  -d '{
  "plan": "eCS1",
  "image": "ubuntu-2204",
  "location": "it-fr2",
  "notes": "my-first-server"
  }'

La risposta sarà simile alla seguente:

{
  "status": "ok",
  "action_id": 37430,
  "server": {
    "name": "ec205827",
    "ipv4": "",
    "ipv6": "",
    "group": null,
    "plan": "eCS1",
    "plan_size": {
      "core": "1",
      "ram": "1024",
      "disk": "20",
      "gpu": "0",
      "gpu_label": null,
      "host_type": "ECS"
    },
    "reserved_plans": [],
    "is_reserved": false,
    "reserved_until": "",
    "support": null,
    "location": "it-fr2",
    "location_label": "Frosinone",
    "notes": "my-first-server",
    "so": "ubuntu-2204",
    "so_label": "Ubuntu Linux 22.04 LTS",
    "creation_date": "2024-10-24T14:43:13.150586+00:00",
    "deletion_date": null,
    "active_flag": false,
    "status": "Booting",
    "progress": 0,
    "api_version": "v4",
    "user": "eCS00099"
  }
}

Monitorare la Creazione

Per monitorare la creazione del server è possibile utilizzare il campo 'action_id' ricevuto nella precedente richiesta (nell'esempio: '37430').

È possibile farlo con la seguente richiesta:

curl -X GET https://api.seeweb.it/ecs/v2/actions/37430 \
  -H 'Authorization: Bearer *il tuo token*'

La risposta sarà simile alla seguente:

{
  "status": "ok",
  "action": {
    "id": 37430,
    "status": "in-progress",
    "user": "eCS00099",
    "created_at": "2024-10-24T14:43:13.611722+00:00",
    "started_at": "2024-10-24T14:43:13.611449+00:00",
    "completed_at": null,
    "resource": "ec205827",
    "resource_type": "ECS",
    "type": "create_server",
    "progress": 25
  }
}

È possibile monitorare l'azione fino a che lo stato non diventa 'completed':

{
  "status": "ok",
  "action": {
    "id": 37430,
    "status": "completed",
    "user": "eCS00099",
    "created_at": "2024-10-24T14:43:13.611722+00:00",
    "started_at": "2024-10-24T14:43:13.611449+00:00",
    "completed_at": "2024-10-24T14:52:13.611449+00:00",
    "resource": "ec205827",
    "resource_type": "ECS",
    "type": "create_server",
    "progress": 100
  }
}

Visualizzare il Server

Ora è possibile visualizzare il Server creato utilizzando la seguente richiesta:

curl -X GET https://api.seeweb.it/ecs/v2/servers/ec205827 \
  -H 'Authorization: Bearer *il tuo token*'

E ottenendo:

{
  "status": "ok",
  "server": {
    "name": "ec205827",
    "ipv4": "213.171.185.95",
    "ipv6": "2001:4b7e:0100:025d::1",
    "group": null,
    "plan": "eCS1",
    "plan_size": {
      "core": "1",
      "ram": "1024",
      "disk": "20",
      "gpu": "0",
      "gpu_label": null,
      "host_type": "ECS"
    },
    "reserved_plans": [],
    "is_reserved": false,
    "reserved_until": "",
    "support": null,
    "location": "it-fr2",
    "location_label": "Frosinone",
    "notes": "my-first-server",
    "so": "ubuntu-2204",
    "so_label": "Ubuntu Linux 22.04 LTS",
    "creation_date": "2024-10-24T14:51:03.360567+00:00",
    "deletion_date": null,
    "active_flag": true,
    "status": "Booted",
    "progress": 100,
    "api_version": "v4",
    "user": "seeweb_test",
    "virttype": "KVM"
  }
}

Cosa fare se lo stato del Server è 'Customizing'

Se si va a verificare lo 'status' del Server appena l'azione viene segnata come 'completed' il Server potrebbe essere ancora nello stato 'Customizing'. Questo stato indica che il Server è stato creato ma è ancora in corso una personalizzazione su di esso, Alcune funzioni potrebbero quindi non essere disponibili, basta aspettare qualche minuto e attendere che lo stato passi a 'Booted'.