Häufige API-Anwendungsfälle

Auf dieser Seite zeigen wir Ihnen anhand einiger einfacher Beispiele, wie Sie gängige Aufgaben mit der Xelon HQ REST API durchführen können.

Wir zeigen Codebeispiele für jedes Szenario unter Verwendung von cURL. Für jede Anfrage ist ein Service Token erforderlich. Besorgen Sie sich also Ihr Token und ersetzen Sie den Wert in den Beispielen.

Erhalten Sie Ihre Tenant ID

Lassen Sie uns zuerst sehen, wie wir unsere Tenant-ID erhalten können - ein sehr nützlicher Parameter in unserem API-Ökosystem.

Wir senden einen GET Request an den tenants Endpunkt auf https://hq.xelon.ch/api/service/tenants.

curl --location --request GET 'https://hq.xelon.ch/api/service/tenants' \
--header 'Authorization: Bearer 0a1b2c3d4e5f6g7h8aBcDeF012345678'

Autorisierungshinweis

Bei jeder Anfrage an die Xelon HQ API übergeben wir einen Autorisierungsheader vom Typ Bearer mit unserem Service-Token. In der Beispielvorlage ist das Token auf 0a1b2c3d4e5f6g7h8aBcDeF012345678 gesetzt, aber Sie sollten es durch Ihr eigenes Token ersetzen.

Die API antwortet mit einem 200-Status und einer JSON-Antwort, die ein Array aller verfügbaren Tenants und ihrer IDs enthält:

[
    {
        "deleted_at": null,
        "active": true,
        "id": "4sn57783n",
        "name": "Xelon AG",
        "address": "Proreznaya str.\nProreznaya_2 str.\n12345\nKyiv\nUkraine",
        "type": "Reseller",
        "created_at": "2018-01-24 20:36:13",
        "networks": 14,
        "activeDevices": 13,
        "parent": null
    },
    {
        "deleted_at": null,
        "active": true,
        "id": "a84bv00609453x",
        "name": "Andrik",
        "address": "Khreschatik st.879, Kyiv, Ukraine\nKhreschatik st.879, Kyiv, Ukraine\n12345\nKyiv\nSwitzerland",
        "type": "Reseller",
        "created_at": "2020-10-13 18:54:05",
        "networks": 1,
        "activeDevices": 1,
        "parent": "4sn57783n"
    }
}

Wir suchen einen Tenant von Xelon AG, unsere Tenant ID ist 4sn57783n.

In der Response können Sie die Anzahl der aktiven Geräte und Netzwerke sehen und ob der Tenant eine übergeordnete-/ Stammorganisation hat.

Geräteliste abrufen

Nun verwenden wir unsere Tenant-ID, um eine Liste der mit unserer Organisation verknüpften Geräte abzurufen.

Wir senden einen GET Request an den devices Endpunkt auf https://hq.xelon.ch/api/service/<TENANT_ID>/devices. Wie beim vorherigen Request senden wir den gleichen Autorisierungsheader mit dem Service-Token vom Typ Bearer.

curl --location --request GET 'https://hq.xelon.ch/api/service/4sn57783n/devices' \
--header 'Authorization: Bearer 0a1b2c3d4e5f6g7h8aBcDeF012345678'

Die API gibt eine Antwort mit dem Status 200 und einer JSON-Antwort zurück, die eine Liste der Geräte enthält, die unserem Tenant zugewiesen sind:

{
    "current_page": 1,
    "data": [
        {
            "localvmid": "638e9e393a43",
            "created_at": "2022-01-28T14:30:53+01:00",
            "updated_at": "2022-01-28T14:32:03+01:00",
            "deleted_at": null,
            "vmdisplayname": "Andrii Device",
            "template_id": 10027,
            "vmhostname": "andrii-test-device",
            "state": 1,
            "iso_mounted": null,
            "serviceuser_status": 0,
            "serviceuser_lastchecked": null,
            "hv_system_id": 4,
            "user_id": 3258,
            "vdc_service_type": 1,
            "service_id": null,
            "monitoring": 1,
            "notes": null,
            "service_cluster_type": null,
            "backup_status": false,
            "power_state": "poweredOn",
            "memory": 7,
            "cpu": 7,
            "hv_type": "public",
            "template": {
                "id": 10027,
                "category": "Server",
                "type": "Linux",
                "instructions": null,
                "hv_type": null
            },
            "tenant": {
                "tenantname": "Xelon AG",
                "tenant_identifier": "2sn54783n"
            },
            "hv_system": {
                "id": 4,
                "created_at": "2022-02-02T13:49:54+01:00",
                "updated_at": "2020-12-03T22:42:42+01:00",
                "custom_template_folder": "group-v127",
                "datacenterName": "datacenter-2",
                "type": 2,
                "tenant_id": 1,
                "main_cloud": 1,
                "display_name": "Test Public",
                "default_lan": null,
                "hv_type": "public"
            }
        }
    ]
}

Innerhalb des Requests finden wir unser localvmid – 638e9e393a43. Jetzt können wir mit der Gerätekonfiguration spielen.

Ein Gerät erstellen

Um ein Gerät über den API-Request zu erstellen, müssen wir seine Konfiguration als JSON-Body-Anfrage senden. Wir verwenden die POST-Methode und einen https://vdc.xelon.ch/api/service/vmlist/create Endpunkte.

Beispiel für einen Request

curl --location --request POST 'https://vdc.xelon.ch/api/service/vmlist/create' \
--header 'Content-Type: application/json' \
--data-raw '{
	"backupId": 1,
	"cloudId": 1,
	"cpucores": 1,
	"disksize": 32,
	"displayname": "test",
	"hostname": "test",
	"ipaddr1": 415,
	"memory": 1,
	"monitoring": false,
	"networkid1": 35,
	"niccontrollerkey1": 100,
	"nickey1": 4000,
	"nicnumber": 1,
	"nicunit1": 7,
	"password": "q3nR5E3;zP",
	"password_confirmation": "q3nR5E3;zP",
	"scriptid": null,
	"sendEmail": false,
	"swapdisksize": 1,
	"template": 1,
	"tenant_identifier": "75c7cf02b782"
}'

Request Felder

Parameter	Type	Description
`backupId`	integer	Specific backup frequency. See the Backups folder for more info.
`cloudId`	integer	An ID of a selected cloud.
`cpucores`	integer	Number of CPU cores. Min: 1; Max: 12.
`disksize`	integer	Number of disk size gigabytes. Min: 32; Max: 4000.
`ipaddr1`	integer	An ID of a selected IP address.
`memory`	integer	Amount of RAM GB. Min: 1; Max: 64
`monitoring`	boolean	Becomes `true` or `false` depending on whether the Monitoring Service toggle is switched on/off.
`networkid1`	integer	An ID of a selected network.
`password`	string	Must contain uppercase and lowercase letters, numbers, and have 6 characters minimum length.
`scriptid`	integer	An ID of a selected script to run after a device setup (optional. For more info, see the Templates, ISOs, and Scripts folder.
`sendEmail`	boolean	If `true`, will email a user when provisioning has been completed
`swapdisksize`	integer	Size of a SWAP disk, GB. Min: 1; Max: 20.
`template`	integer	Selected OS. Explore the Device creation info endpoint above for more details.

Innerhalb einer 200 Response, der Endpunkt zeigt die Informationen des erstellten Geräts an, einschliesslich der unten aufgeführten Parameter.

Response Beispiel

{
  "device": {
    "localvmid": "",
    "hv_system_id": 1,
    "template_id": 1,
    "vmdisplayname": "test",
    "iso_mounted": null,
    "vmhostname": "test",
    "state": 0,
    "user_id": 1695,
    "updated_at": "2022-03-17T15:52:34+01:00",
    "created_at": "2022-03-17T15:52:34+01:00",
    "monitoring": false,
    "vdc_service_type": 1,
    "hv_type": "public"
  },
  "ips": [
    "10.0.0.4"
  ]
}

Response Felder

Parameter	Type	Description
`localvmid`	integer	An ID of your device.
`vmdisplayname`	string	A name of your device which will be displayed within the interface.
`iso_mounted`	integer	An ID of a connected ISO, if available.
`monitoring`	boolean	If `true`, the Monitoring Service is enabled.
`ips`	array	An array of the network's IP addresses linked to this device.
`state`	integer	`1` – provisioning finished, the device is ready; `0` – provisioning in progress or failed
`hv_system_id`	integer	Hypervisor's ID (learn more in a Get list of organization's clouds endpoint)
`service_id`	string	ID of a cluster (if it's related to Kubernetes cluster)

Das war's! Ihr Gerät wurde erstellt und befindet sich jetzt etwa 15 Minuten lang im Bereitstellungsprozess. Danach können Sie mit der Konfiguration beginnen.

CPU und RAM zu einem Gerät hinzufügen

Lassen Sie uns etwas RAM und CPU-Kerne zu unserem eigenen Gerät hinzufügen.

Dieses Mal senden wir eine PUT-Anfrage an den vmlist-Endpunkt unter

https://hq.xelon.ch/api/service/vmlist/<LOCALVMID>/updateserver. Ausserdem fügen wir unserer Anfrage zwei Integer-Parameter hinzu: ramvalue and cpuvalue.

curl --location --request PUT 'https://hq.xelon.ch/api/service/vmlist/638e9e393a43/updateserver?ramvalue=12&cpuvalue=6' \
--header 'Authorization: Bearer 0a1b2c3d4e5f6g7h8aBcDeF012345678'

Nicht so schnell!

Beachten Sie bitte, dass RAM, CPU und andere Werte ihre Grenzen haben. Erfahren Sie mehr darüber in unserer API-Referenzdokumentation.

Die API antwortet mit einem Status 200 und einer JSON-Antwort, die eine entsprechende Nachricht enthält.

{
	"message": "Server is upgrading"
}

Eine Reseller-Organisation erstellen

Um eine Organisation vom Typ "Reseller" zu erstellen, müssen wir eine POST-Anfrage an den Endpunkt https://vdc.xelon.ch/api/user/tenants/store senden. Hier ist, was im Anfrage-Body enthalten sein sollte:

{
	"2factor": <true OR false>,
	"address": "<ADDRESS>",
	"city": "<CITY>",
	"country": "<COUNTRY>",
	"financeemail": "<EMAIL>",
	"phone": "<PHONE>",
	"postcode": "<ZIPCODE>",
	"supportemail": "<EMAIL>",
	"tenantname": "<RESELLER_ORG_NAME>",
	"trial": false,
	"type": "1"
}

Parameter	Description	Type
`2factor`	If `true`, will enable a 2-factor authentication for all organization's users.	boolean
`address`	Organization's address.	string
`city`	Organization's city name.	string
`country`	A string value with the country name.	string
`financeemail`	Organization's finance email.	string
phone	Organization's phone number.	string
`postcode`	Organization's ZIP/post code.	string
`supportemail`	Organization's support email.	string
`tenantname`	Display name of your organization.	string
`trial`	Set to `false`.	boolean
`type`	Set `1` for Reseller, and `2` for End customer organization type.	string

In der 200-Antwort erhalten wir eine "message", die besagt, dass "The organization was successfully created.". Im tenant-Parameter oder der Antwort erhalten Sie Informationen zu Ihrer neuen Untergeordneten Organisation.

So sieht der Curl-Request aus:

curl --location --request POST 'https://vdc.xelon.ch/api/service/tenants/store' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9kZXYtdmVyLTFcL1wvYXBpXC91c2VyXC9sb2dpbiIsImlhdCI6MTU4MjEwMzA1OSwiZXhwIjoxNTgyMTA0MjU5LCJuYmYiOjE1ODIxMDMwNTksImp0aSI6IkNhNlJZNFc3RDc0M3dwVHEiLCJzdWIiOjMwMywicHJ2IjoiODdlMGFmMWVmOWZkMTU4MTJmZGVjOTcxNTNhMTRlMGIwNDc1NDZhYSJ9.dehIFqzjOMi6nexVGjngO-co0EUXTav4TqPJtjvGW7g' \
--header 'Content-Type: application/json' \
--data-raw '{
	"2factor": false,
	"address": "Test Address",
	"city": "Zug",
	"country": "Switzerland",
	"financeemail": "<EMAIL>",
	"phone": "<PHONE_NUMBER>",
	"postcode": "<ZIP>",
	"supportemail": "<EMAIL>",
	"tenantname": "<ORGANIZATION_NAME>",
	"trial": false,
	"type": "1"
}'

Das war's! Wir haben die grundlegenden Konzepte der Interaktion mit der Xelon HQ REST API behandelt. Wie bereits erwähnt, finden Sie alle Details zu den verfügbaren Endpunkten und Parametern für die verschiedenen Xelon HQ-Instanzen in der API-Referenzdokumentation.