Nutzung der API

CenturyLink Public Cloud provides an API for performing the same actions programmatically as you can from within the Control Portal. Diese API ist RESTful, nutzt JSON-Nachrichten über HTTP und basiert auf den gängigen HTTP-Methoden, darunter GET, POST, PUT, DELETE und PATCH. Das allgemeine URL-Format des Service lautet: https://api.ctl.io/v2/{resource}/{account alias}.

Die folgende Demo verwendet unbearbeitete HTTP-Anfragen, um ein Beispiel der Verwendung der API zur Erstellung eines Servers aufzuzeigen. Natürlich können Sie eine beliebige Programmiersprache wählen, die die Verarbeitung von HTTP-Anfragen und -Antworten mit JSON-Nachrichten unterstützt. Für eine vollständige Liste aller unterstützten API-Methoden lesen Sie unsere API-Dokumentation.

Authentifizierung über die API

Bei der Authentifizierung über die API v2 werden dieselben Anmeldedaten verwendet wie bei dem Zugriff auf das CenturyLink Cloud Control Portal. Der Benutzername und das Passwort werden an die API gesendet. Im Gegenzug erhält der Benutzer ein Anmeldedatenobjekt zurück. Dieses Objekt enthält ein gültiges Bearer Token, das für eine nachfolgende API-Anfrage bereitgestellt werden muss und bis zu 2 Wochen lang wiederverwendet werden kann. Außerdem muss die HTTP-Anfrage einen Content-Type-Header beinhalten, der auf application/json gesetzt ist.

Unten ist ein Beispiel einer groben HTTP-Anfrage mit Antwortnachrichten beim Abrufen eines gültigen Tokens von dem API-Authentifizierungsdienst. (Hinweis: Das tatsächliche Bearer Token und das Passwort wurden zu Demonstrationszwecken durch eine zufällige Zeichenfolge ersetzt.)

Anfrage

POST https://api.ctl.io/v2/authentication/login HTTP/1.1
Host: api.ctl.io
Content-Type: application/json

{
  "username": "trent.anderson",
  "password": "P@ssw0rd1"
}

Antwort

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Date: Thu, 26 Mar 2015 19:14:15 GMT
Content-Length: 541

{
  "roles" : [
    "ServerAdmin"
  ],
  "userName" : "trent.anderson",
  "bearerToken" : "VGCVlA1JK5WLEXicGVujiJblEIApnIJhicZcNZG1MjvJI5IQXJime3tzQYOYHjLuX2NiZLiJvTRi2JOXdcbkX46UWzmIZnJIzpM6JjpmJDB.iX91ML6IzhdX62cekloAB6uJUOjjoi1xClUOBXZmXJxciUzdje2MJM96VM1Mk4NOXubYIXbbiwf06E1YQbeEsKIy1HdizndJWyJVs4XCGiwpTdlyiRXkGrikopi0I5pI.6RYzOrI2lj4bYZsJzeWXGCRNpyXjIbbJLcJL3ckH4CjbisZnZJYMiiIYgD1plIa9JUXuFUG4iymCQV2JXiJluZiziRJYk0b1VJhIRc3M13ihOe",
  "accountAlias" : "BTDI",
  "locationAlias" : "WA1"
}

Diese Ergebnisse zeigen das Hauptkonto des Benutzers, die Standard-Standort des Rechenzentrums und die zugewiesenen Plattformrollen. Das Bearer Token ist der Wert, der dem HTTP-Authorization-Header beim Aufruf eines anderen API-Services hinzugefügt werden muss. Dieses Token identifiziert den Benutzer und legt fest, was dieser in der API tun darf.

Falls die von Ihnen zur Verfügung gestellten Anmeldedaten ungültig sind, erhalten Sie eine HTTP 400 (Ungültige Anforderung) mit folgender Antwortnachricht:

HTTP/1.1 400 Bad Request
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Date: Thu, 26 Mar 2015 19:15:22 GMT
Content-Length: 89

{"message":"We didn't recognize the username or password you entered. Please try again."}

Mittels API einen Server erstellen

Die nachfolgende grobe HTTP-Anfrage zeigt, wie ein Benutzer eine sichere API-Anfrage stellen kann, um einen Server zu erstellen. Beachten Sie, dass das Bearer Token der vorherigen Authentifizierungsanfrage zum Header dieser Anfrage hinzugefügt wurde. Die JSON-Daten beinhalten alle für die Erstellung eines neuen Servers notwendigen Informationen, darunter den Namen, die Beschreibung, das Template, das Passwort, Größeninformationen sowie die Kennung der übergeordneten Gruppe, die den Server verwendet (entweder aus der URL des Control Portal oder über einen Link aus einer vorherigen API-Anfrage für diese Gruppe bezogen).

Anfrage

POST https://api.ctl.io/v2/servers/BTDI HTTP/1.1
Host: api.ctl.io
Content-Type: application/json
Authorization: Bearer VGCVlA1JK5WLEXicGVujiJblEIApnIJhicZcNZG1MjvJI5IQXJime3tzQYOYHjLuX2NiZLiJvTRi2JOXdcbkX46UWzmIZnJIzpM6JjpmJDB.iX91ML6IzhdX62cekloAB6uJUOjjoi1xClUOBXZmXJxciUzdje2MJM96VM1Mk4NOXubYIXbbiwf06E1YQbeEsKIy1HdizndJWyJVs4XCGiwpTdlyiRXkGrikopi0I5pI.6RYzOrI2lj4bYZsJzeWXGCRNpyXjIbbJLcJL3ckH4CjbisZnZJYMiiIYgD1plIa9JUXuFUG4iymCQV2JXiJluZiziRJYk0b1VJhIRc3M13ihOe

{
  "name": "rhel",
  "description": "My RedHat Server",
  "groupId": "60582771e45fe111ba2500505682315a",
  "sourceServerId": "RHEL-6-64-TEMPLATE",
  "password": "P@ssw0rd1",
  "cpu": 2,
  "memoryGB": 4,
  "type": "standard",
  "storageType": "standard"
}

Die Antwort lautet HTTP 202 Accepted (anstatt HTTP 200 OK), wodurch angezeigt wird, dass die Anfrage ein lang andauernder Prozess ist und dass ein Auftrag der Warteschlange hinzugefügt wurde, um die Erstellung des Servers abzuschließen. Darüber hinaus wird eine JSON-Nachricht zurückgesendet, die Informationen über den neu angeforderten Server sowie einen Link zur Auftragsstatus-API enthält, um den Abschluss der Anfrage weiter zu verfolgen.

Antwort

HTTP/1.1 202 Accepted
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Date: Thu, 26 Mar 2015 22:27:24 GMT
Content-Length: 265

{
  "server" : "rhel",
  "isQueued" : true,
  "links" : [
    {
      "rel" : "status",
      "id" : "wa1-143253",
      "href" : "/v2/operations/btdi/status/wa1-143253"
    },
    {
      "rel" : "self",
      "id" : "be96b91d4eef4789b81184992c9ac821",
      "href" : "/v2/servers/BTDI/be96b91d4eef4789b81184992c9ac821?uuid=True",
      "verbs" : [
        "GET"
      ]
    }
  ]
}