API-Anforderungen für die API-Integration

Dieses Dokument beschreibt die allgemeinen Anforderungen einer API, die Sie als Typanbieter in Deployment Manager hinzufügen möchten. Verwenden Sie diese Richtlinien, um die Merkmale einer API zu verstehen, die Deployment Manager erwartet. Wenn Ihre API nicht genau den hier beschriebenen Spezifikationen entspricht, können Sie mögliche Inkonsistenzen eventuell mit den erweiterten API-Optionen auflösen.

Gültiges Deskriptordokument der API

Ein Deskriptordokument beschreibt eine API und deren Ressourcen. In Deployment Manager können nur APIs integriert werden, die durch eine OpenAPI-Spezifikation oder ein Google Discovery-Deskriptordokument abgesichert sind. Ausführliche Informationen zum Erstellen einer OpenAPI-Spezifikation finden Sie im OpenAPI GitHub-Repository.

Zugänglicher Endpunkt des API-Deskriptordokuments

Deployment Manager erstellt eine HTTP-Anfrage, um das Deskriptordokument der API abzurufen. Stellen Sie daher sicher, dass Ihr Deskriptordokument an einer Stelle gehostet wird, auf die Deployment Manager zugreifen kann. Es kann sich dabei um eine öffentlich zugängliche URL handeln oder einen Endpunkt, der von einer Basisauthentifizierung geschützt wird.

Von API akzeptierte Basis- oder OAuth2-Authentifizierung bei bestimmten Google-Diensten

Deployment Manager unterstützt derzeit die einfache Authentifizierung (Nutzername und Passwort) und die OAuth 2.0-Authentifizierung für bestimmte APIs, die auf Google Kubernetes Engine oder auf Google Endpoints gehostet werden. Sie können die Authentifizierung so einrichten, dass die Dienstkonten des Projekts verwendet werden.

Weitere Informationen finden Sie unter Typanbieter erstellen.

Unterstützung für Erstellen, Lesen, Aktualisieren und Löschen (CRUD)

Die betreffende API muss eine RESTful API sein, die das Erstellen, Lesen, Aktualisieren und Löschen, also sogenannte CRUD-Vorgänge (CRUD = Create, Read, Update und Delete), unterstützt. Das heißt, es gibt Methoden, die Folgendes ausführen:

  • Erstellvorgänge erstellen Ressourcen. Dies müssen HTTP POST-Anfragen sein.
  • Lesevorgänge rufen Informationen zu API-Ressourcen ab. Dies müssen HTTP GET-Anfragen sein.
  • Aktualisierungsvorgänge aktualisieren eine Ressource. Dies müssen HTTP PUTAnfragen sein.
  • Löschvorgänge entfernen Ressourcen. Dies müssen HTTP DELETE-Anfragen sein.

Eine API, die CRUD-Vorgänge nur teilweise unterstützt, funktioniert zwar weiterhin, aber das Verhalten unterscheidet sich je nach Verfügbarkeit der Vorgänge.

Unterstützt GET-Anfragen Unterstützt CREATE-Anfragen Unterstützt UPDATE-Anfragen Unterstützt DELETE-Anfragen Besonderes API-Verhalten
Ja Ja Ja Ja Keines
Ja Ja Ja Nein Nutzer können eine Ressource verwerfen, aber nicht löschen.
Ja Ja Nein Ja Alle Änderungen an einer vorhandenen Ressource würden fehlschlagen. Nutzer müssen eine Ressource löschen und neu erstellen, um sie zu aktualisieren.
Ja Ja Nein Nein Beide oben beschriebenen Verhaltensweisen.
Ja Nein Ja Ja Falls eine API Erstellungsanfragen nicht unterstützt, können Nutzer der Bereitstellung vorhandene Ressourcen hinzufügen, indem Sie die Bereitstellung mit der Richtlinie ACQUIRE aktualisieren.
Ja Nein Ja Nein Nutzer können eine Ressource abrufen oder nach Abrufen aktualisieren, aber die Ressource kann nicht gelöscht werden.
Ja Nein Nein Ja Nutzer können eine Ressource löschen und beziehen oder der Bereitstellung eine vorhandene Ressource hinzufügen.
Ja Nein Nein Nein Nutzer können eine vorhandene Ressource hinzufügen oder mit der ABANDON-Richtlinie entfernen.

Pfad- und Abfrageparameter erfolgreich auflösen

Alle Pfad- und Abfrageparameter der API müssen als Teil des Ressourcentextes oder in allen API-Methoden vorhanden sein, sodass Deployment Manager den Parameter bei der Bereitstellung durch einen Nutzer zuordnen kann. Die folgenden Bedingungen gelten für Pfad- und Abfrageparameter.

Jeder Pfad-/Abfrageparameter für POST muss ein Parameter für PUT sein

Folgendes ist ungültig, weil myParameter für POST aber nicht für PUT vorhanden ist:

POST  /my-api/{myParameter}/resource/{mySecondParameter}
PUT   /my-api/resource/{mySecondParameter}  # myParameter is not present

Jeder Parameter für Nicht-POST-Methoden muss in allen Methodenschnittstellen oder als Teil der Ressource vorhanden sein. Wenn dieser Parameter vom Server generiert wird, sind weitere Überlegungen erforderlich.

In einem Szenario für den günstigsten Fall könnte die API so aussehen. Dabei wird der Parameter name für alle Methoden angezeigt.

POST   /my-api/my-resource/{name}
PUT    /my-api/my-resource/{name}
GET    /my-api/my-resource/{name}
DELETE /my-api/my-resource/{name}

In einem anderen Szenario könnte ein Feld als Pfadparameter für eine Methode angezeigt werden, nicht aber als Pfadparameter für andere Methoden. In diesem Fall sollte das Feld Teil der API-Ressource sein. Beispiel:

POST  /my-api/my-resource ← the 'id' field  is not present on the POST request
GET   /my-api/my-resource/{id}

schema for my-resource
type: object
properties:
# id is part of the resource so Deployment Manager will use this value for
# POST requests after creation
  id:
    type: string

In diesem Beispiel wird angenommen, dass id ein vom Server generierter Wert ist. Dieser ist in der Ressource enthalten, aber nicht vorhanden, wenn eine POST-Anfrage gestellt wird. Wenn das Attribut id erforderlich ist, um eine Anfrage an eine vorhandene Ressource zu stellen, das Attribut aber nicht in der Ressource enthalten oder im Pfad verfügbar ist, kommt es beim Portieren der API zu Deployment Manager zu Problemen.

Schwieriges API-Verhalten erfordert zusätzliche Konfiguration

Es gibt bestimmte API-Verhaltensweisen, die eine zusätzliche API-Konfiguration erfordern, damit die API mit Deployment Manager integriert werden kann. Solche Verhaltensweisen sind:

  • Vom Server generierte Werte: Einige API-Ressourcen haben servergenerierte Attribute, die sich nach jeder Anfrage oder bei einem bestimmten Ereignis in der API ändern. Sie können erweiterte API-Optionen verwenden, um Deployment Manager anzuweisen, diese neuen Werte bei jeder Anfrage abzurufen.

    Beispielsweise kann eine API das neueste Fingerabdruckattribut einer Ressource anfordern, bevor sie eine Aktualisierungsanfrage zulässt. Verwenden Sie erweiterte API-Optionen, um Deployment Manager anzuweisen, diesen Wert jedes Mal abzurufen, wenn ein Nutzer eine Anfrage zur Aktualisierung einer Bereitstellung durch diesen Wert stellt.

  • Nutzereingaben bearbeiten: Wenn Ihre API zum Beispiel erfordert, dass dem Wert eines Feldes immer das Präfix einer Projekt-ID vorangestellt sein muss, können Sie die Eingabezuordnungen dazu verwenden, diese Informationen automatisch hinzufügen. Die Nutzer müssen diese dann nicht manuell eingeben.

  • Feldwerte, die sich mit jeder Methode ändern: Bei Methoden, die dasselbe Feld, aber mit anderen Werten wiederverwenden, können Sie Deployment Manager mit den API-Optionen mitteilen, wann welcher Wert verwendet werden soll.

Weitere Informationen finden Sie unter Erweiterte API-Optionen festlegen.

Weitere Informationen