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 muss über eine HTTP POST-Anfrage erfolgen.
  • Lesevorgänge rufen Informationen zu API-Ressourcen ab. Dies muss über eine HTTP GET-Anfrage erfolgen.
  • Aktualisierungsvorgänge aktualisieren eine Ressource. Dies muss über eine HTTP PUT-Anfrage erfolgen.
  • Löschvorgänge entfernen Ressourcen. Dies muss über eine HTTP DELETE-Anfrage erfolgen.

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 lesen oder aktualisieren, aber die Ressource kann nicht gelöscht werden.
Ja Nein Nein Ja Nutzer können eine Ressource löschen und lesen 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 vorhanden ist, aber nicht für PUT:

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 Methodeschnittstellen oder als Teil der Ressource vorhanden sein. Es gelten besondere Überlegungen, wenn dieser Parameter vom Server generiert wird.

In einem Szenario für den günstigsten Fall könnte die API folgendermaßen aussehen, wobei der name-Parameter für alle Methoden angezeigt wird.

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

Dieses Beispiel geht von der Annahme aus, dass id ein vom Server generierter Wert ist, der sich in der Ressource befindet, aber bei der POST-Anfrage nicht vorhanden ist. Wenn die id-Eigenschaft erforderlich war, um eine Anfrage an eine vorhandene Ressource zu senden, aber die Eigenschaft nicht in der Ressource oder dem Pfad verfügbar war, verursacht dies Reibung beim Portieren der API zu Deployment Manager.

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 verfügen über 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 Fingerabdrucksattribut einer Ressource anfordern, bevor sie eine Aktualisierungsanfrage zulässt. Verwenden Sie erweiterte API-Optionen, um Deployment Manager anzuweisen, diesen Wert jedes Mal abzurufen, wenn Ihr Nutzer eine Anfrage zur Aktualisierung einer Bereitstellung durch diesen Wert stellt.

  • Nutzereingaben manipulieren: 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. Ihre 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

Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...

Cloud Deployment Manager-Dokumentation