API verwenden

Last change on 2023-07-25 • Created on 2022-11-21 • ID: CL-09EB0

  1. Nutzen Sie Ihren API-Token

    Um die API nutzen zu können, benötigen Sie einen API-Token. Achten Sie darauf, dass Sie für jedes Projekt einen eigenen API-Token erstellen müssen, da jeder API-Token an das Projekt gebunden ist, in dem er erstellt wurde und für kein zweites Projekt genutzt werden kann.

    Wenn Sie noch keinen API-Token besitzen, erstellen Sie diesen jetzt. Im Getting Started "API-Token hinzufügen" wird Schritt für Schritt erklärt wie das geht. Denken Sie daran den API-Token nach dem Erstellen zu kopieren und zu speichern, da es nicht möglich ist sich diesen erneuet anzeigen zu lassen.

    In allen Beispiel-Befehlen wird $API_TOKEN als Platzhalter angegeben. Beachten Sie, dass $API_TOKEN mit Ihrem tatsächlichen API-Token ersetzt werden muss. Beispiel:

    -H "Authorization: Bearer $API_TOKEN" \
    -H "Authorization: Bearer jEheVytlAoFl7F8MqUQ7jAo2hOXASztX" \
    Beispiel-Projekt
    Projekt 1
    $API_TOKEN_1
    2x
    Server
    2x
    Primary IP
    1x
    Privates Netzwerk
    Projekt 2
    $API_TOKEN_2
    1x
    Server
    1x
    Primary IP
    1x
    Firewall


    Um über die zwei Server in "Projekt 1" Informationen anzufragen, müssen Sie im Curl-Befehlen $API_TOKEN_1 angeben:

    curl \
       -H "Authorization: Bearer $API_TOKEN_1" \
       'https://api.hetzner.cloud/v1/servers'

  1. Nutzen Sie die Dokumentation

    Öffnen Sie die Cloud API Dokumentation und nutzen Sie die linke Menüleiste, um zu den Punkten zu navigieren, die für Sie relevant sind.

    cloud-api-docs

    Je nachdem was Sie anfragen möchten, müssen Sie einen von vier Requests ausführen.

    Die vier Requests im Überblick
    GET
    Read
    curl \
      -H "Authorization: Bearer $API_TOKEN" \
      'https://api.hetzner.cloud/v1/{api-url-ending}'
    Information über verfügbare Tarife, Ressourcen, Standorte oder anderes anfragen.

    POST
    Read & Write
    curl \
      -X POST \
      -H "Authorization: Bearer $API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"eigenschaft":wert,"eigenschaft":wert,...}' \
      'https://api.hetzner.cloud/v1/{api-url-ending}'
    Neue Ressourcen erstellen und/oder konfigurieren

    PUT
    Read & Write
    curl \
      -X PUT \
      -H "Authorization: Bearer $API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"eigenschaft":wert,"eigenschaft":wert,...}' \
      'https://api.hetzner.cloud/v1/{api-url-ending}/{id}'
    Die Eigenschaften bestehender Ressourcen bearbeiten

    DELETE
    Read & Write
    curl \
      -X DELETE \
      -H "Authorization: Bearer $API_TOKEN" \
      'https://api.hetzner.cloud/v1/{api-url-ending}/{id}'
    Bestehende Ressourcen löschen

  1. Curl-Befehl kopieren

    Sobald Sie zu einem der Punkte navigiert haben, sehen Sie sich den "HTTP Request" an:

    api-request

    Der "HTTP Request" besteht aus zwei Teilen <request-type> <api-url-ending>.

    Mit dieser Information erfahren Sie, welchen Curl-Befehl Sie ausführen müssen. Am rechten Rand der API-Dokumentation gibt es zusätzlich noch einen Beispiel-Befehl. In diesem Beispiel ("HTTP Request": GET /servers), wäre der entsprechende Curl-Befehl:

    api-request 

    curl \
    -H "Authorization: Bearer $API_TOKEN" \
    'https://api.hetzner.cloud/v1/servers'

    Beachten Sie, dass $API_TOKEN mit dem eigenen API-Token ersetzt werden muss.

    Der Curl-Befehl erklärt
    • -X {request-type} Mit der ersten Zeile wird normalerweise bestimmt, welche Art von Request es ist. Bei GET Requests wird diese Zeile aber nicht benötigt.
    • -H "Authorization: Bearer $API_TOKEN" In dieser Zeile wird der API-Token angegeben. Da der API-Token an ein bestimmtes Projekt gebunden ist, wird hiermit bestimmt in welchem Projekt der Request ausgeführt werden soll.
    • Bei POST und PUT Requests müssen manchmal bestimmte Eigenschaften definiert werden, die zum Erstellen oder Bearbeiten einer Ressource erforderlich sind. Eine solche Eigenschaft könnte beispielsweise ein Name ("name":"unique-name") oder der Typ ("type":"ipv4") sein. Um diese Informationen anzugeben, sind zwei zusätzliche Zeilen erforderlich:
      curl \
         -X POST \
         -H "Authorization: Bearer $API_TOKEN" \
      +  -H "Content-Type: application/json" \
      +  -d '{"eigenschaft":wert,"eigenschaft":wert,...}' \
         'https://api.hetzner.cloud/v1/servers'

  1. Eigenschaften zu einem POST oder PUT Request hinzufügen

    Wenn Sie eine neue Ressource erstellen oder eine Bestehende bearbeiten möchten, werden Sie vermutlich Eigenschaften wie einen Namen oder einen Standort angeben müssen.

    Um schnell loszulegen, können Sie schlicht den Beispiel-Befehl am rechten Rand kopieren. Der Beispiel-Befehl enthält alle wesentlichen Eigenschaften und Sie müssen lediglich die Werte anpassen und Eigenschaften, die Sie nicht bestimmen möchten, entfernen. Beachten Sie dabei aber, dass manche Eigenschaften nicht optional sind und angegeben werden müssen. Um mehr über die Eigenschaften zu erfahren, nutzen Sie die Dokumentation unter dem "Request"-Titel. Eigenschaften, die angegeben werden müssen, sind mit required gekennzeichnet.

    api-properties

    Anstatt den Curl-Befehl zu kopieren, können Sie die Eigenschaften auch aus der Dokumentation unter "Request" übernehmen. Alle Eigenschaften werden dort mit Angabe des Wertes und einer kurzen Beschreibung gelistet.

    Eigenschaft Wert
    Beschreibung der Eigenschaft

    Nutzen Sie folgendes Format, um eine Eigenschaft einem Curl-Befehl hinzuzufügen:

    curl \
       -X {request-type} \
       -H "Authorization: Bearer $API_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{"eigenschaft":wert,"eigenschaft":wert,...}' \
       'https://api.hetzner.cloud/v1/{api-url-ending}'

    Die verschiedenen Werte:

    Wert Format
    string "beliebiger-text"
    integer 12
    object {"eigenschaft":wert}
    boolean true
    false
    nullable null
    Beispiel-Request

    Create Resource X

    Request
    name string
    Name of resource
    resource_y integer
    ID of Resource Y which you would like to add to Resource X
    labels object
    User-defined labels (key-value pairs)
      labelkey string
      New label
    delete boolean
    If true, prevents the resource from being deleted
    description string – nullable
    Description of the resource

      Beispiel -d-Zeile im Curl-Befehl:
    -d '{"name":"my-resource","resource_y":18,"labels":{"labelkey":"my-label"},"delete":true,"description":null}'

    Wenn array of ... angegeben wird, können Sie einfach das Format "eigenschaft":[wert] nutzen. Einzelne Werte werden mit einem Komma getrennt:

    array of ... format
    strings ["beliebiger-text","beliebiger-text"]
    integers [12,43]
    objects [{"eigenschaft":wert,"eigenschaft":wert}]

  1. Query-Parameter

    Mit Query-Parametern ist es möglich die Response auf einen Request zu sortieren oder zu filtern. Sie können also beispielsweise bestimmen, dass nur Ressourcen mit einem bestimmten Label angezeigt werden sollen.

    Format zum Verfeinern der Ergebnisse:

    • Ein einfacher Query-Parameter

      https://api.hetzner.cloud/v1/{api-url-ending}?parameter=wert

    • Ein Query-Parameter mit einem Enum-Wert
      "enum values" sind vordefinierte Werte, die Sie direkt kopieren und in der URL einfügen können.

      https://api.hetzner.cloud/v1/{api-url-ending}?parameter={enum-value}

    • Zwei oder mehr Querie-Parameter
      Der erste Parameter, der an eine URL angehängt wird, beginnt mit einem Fragezeichen ?. Allen weiteren Parametern wird ein Und-Zeichen & vorgestellt.

      https://api.hetzner.cloud/v1/{api-url-ending}?parameter=wert&parameter=wert

    Wenn Sie die Response auf einen bestimmten Request sortieren möchten, nutzen Sie die Übersicht unter dem Titel "Query Parameters". Dort sind alle Parameter gelistet, die für einen bestimmten Request verfügbar sind.

    api-query-parameters

    Parameter Wert
    Beschreibung des Parameters
    Beispiele
    • Label Selektoren
       Ressourcen können einfache Label besitzen, die lediglich aus dem key-Teil bestehen und sie können key  value -Paare ("key=value") als Label besitzen. Sie können Ihre Ressourcen entweder nur nach einem bestimmten "key" sortieren oder nach "key" und "value".
      https://api.hetzner.cloud/v1/floating_ips?label_selector=env
      Mit diesem Request könnten Sie eine Liste von Ressourcen erhalten, die als Label env  production , env  testing , oder schlicht env besitzen. Weitere Informationen erhalten Sie in der offiziellen Dokumentation zu Label Selektoren.

    • Sortieren
       Im oberen Beispiel-Bild ist angegeben, dass die Ressourcen nach ID oder nach Erstellungsdatum sortiert werden können. Um die Ergebnisse aufsteigend (engl. ascending asc) nach ID zu sortieren, können Sie einfach den entsprechenden Enum-Wert kopieren.
      https://api.hetzner.cloud/v1/floating_ips?sort=id:asc
      Weitere Informationen erhalten Sie in der offiziellen Dokumentation zu Sortieren.

    • Zwei Parameter in einem Request
      https://api.hetzner.cloud/v1/floating_ips?label_selector=env&sort=id:asc

  1. Den Curl-Befehl ausführen

    Nachdem Sie den Curl-Befehl kopiert und bearbeitet haben, stellen Sie sicher, dass auch der richtige API-Token hinzugefügt wurde. Führen Sie den Befehl anschließend über eine Kommandozeile aus.

Nachdem der Befehl ausgeführt wurde, sollte Ihnen eine Response angezeigt werden, in der Sie erfahren, ob der Befehl erfolgreich war. Alle Änderungen, die über die API vorgenommen werden, werden auch in der Cloud Console angezeigt.


Nächste Schritte: