API-Lebenszyklus verwalten

Auf dieser Seite werden die Features zur Versionsverwaltung der Cloud Endpoints API sowie Best Practices für die Versionsverwaltung und das Staging Ihrer Endpoints API erläutert. Die Informationen gelten für APIs, die der OpenAPI-Spezifikation entsprechen. Informationen zu APIs, die Cloud Endpoints Frameworks für die App Engine-Standardumgebung nutzen, finden Sie unter API-Versionierung handhaben für Java oder API-Versionierung handhaben für Python.

Wir empfehlen, dass Sie dieselben Grundprinzipien beachten, die Google auch für die API-Versionierung und das Dienst-Staging verwendet:

  • Nehmen Sie folgende Änderungen an Ihrer OpenAPI-Konfigurationsdatei vor, bevor Sie die erste Version bereitstellen:

    • Legen Sie im Feld info.version die Versionsnummer fest. Wir empfehlen die Verwendung eines Versionsstrings, der eine Hauptversion und eine Nebenversion enthält, z. B. 1.0.
    • Legen Sie im Feld basePath die Hauptversionsnummer fest. Wir empfehlen die Verwendung eines Basispfads mit dem Buchstaben v, gefolgt von der Hauptversionsnummer, z. B. /v1.

  • Wenn Sie eine abwärtskompatible Änderung vornehmen müssen, z. B. das Einfügen einer neuen Methode, erhöhen Sie die Nebenversionsnummer (1.2, 1.3 usw.) im Feld info.version und führen Sie die Bereitstellung noch einmal durch. Weitere Informationen finden Sie unter API versionieren.

  • Wenn Sie eine Änderung an einer vorhandenen Methode vornehmen müssen, durch die der Clientcode nicht mehr funktioniert, kopieren Sie Ihre OpenAPI-Konfigurationsdatei und ändern Sie das:

    • Erhöhen Sie die Hauptversionsnummer (2.0, 3.0 usw.) im Feld info.version.
    • Erhöhen Sie die Hauptversionsnummer (/v2, /v3 usw.) im Feld basePath.

    Stellen Sie beide Versionen Ihrer OpenAPI-Konfigurationsdateien und das Backend bereit, das jetzt beide Versionen der Methode enthält. Weitere Informationen finden Sie unter API versionieren.

  • Implementieren Sie alle API-Hauptversionen in einem einzelnen Back-End. Diese Empfehlung hat folgende Konsequenzen:

    • Die Weiterleitung wird vereinfacht, da Anfragen an eine bestimmte Version auf dem Pfad basieren, wie im obigen Beispiel.
    • Die Konfiguration und die Bereitstellung werden vereinfacht. Sie verwenden dasselbe Google Cloud-Projekt und dasselbe Back-End für alle Hauptversionen der API und Sie stellen alle Versionen Ihrer API gleichzeitig bereit.
    • Ihre Kosten werden minimiert, da die Ausführung überflüssiger Back-Ends vermieden wird.

  • Testen Sie Ihre API in einem separaten Google Cloud-Projekt, bevor Sie die Bereitstellung in Ihrem Google Cloud-Projekt für die Produktion durchführen. Weitere Informationen finden Sie unter Dienst-Test durchführen.

Die Verwendung der Haupt- und Nebenversionsnummern in Endpoints entspricht den Definitionen in Semantische Versionierung. Es bleibt Ihnen überlassen, ob Sie in Endpoints die Patch-Versionsnummer in Ihrer OpenAPI-Konfigurationsdatei erhöhen und die Konfiguration bereitstellen, wenn Sie eine Fehlerkorrektur in Ihrem Back-End-Code bereitstellen.

Versionierungsfunktionen der Cloud Endpoints API

Der Extensible Service Proxy (ESP) kann mehrere Hauptversionen Ihrer API gleichzeitig in einem einzigen Google Cloud-Projekt und Backend verwalten, sofern sich die Pfade der APIs nicht überlappen. Beispiel:

http://echo-api.endpoints.my-project.cloud.goog/v1/echo
http://echo-api.endpoints.my-project.cloud.goog/v2/echo

Dadurch können Ihre Kunden entscheiden, welche Version sie verwenden möchten, und bestimmen, wann sie zur neuen Version migrieren. Der ESP kennzeichnet jede Anfrage mit der Versionsnummer, bevor er die Anfrage an die jeweilige Methode im Back-End weiterleitet. Jede Anfrage ist mit einer Versionsnummer gekennzeichnet, was folgende Konsequenzen hat:

  • In den Grafiken und Logs in Endpoints > Dienste werden Anfragen von jeder API-Hauptversion und die Gesamtsummen für alle Versionen angezeigt. Sie können Ihre Ansicht für eine bestimmte Version filtern. Dadurch erhalten Sie eine klare Vorstellung davon, wie viel Traffic jede Version erhält. Den Logs kann auch entnommen werden, welche Clients welche Version verwenden.

  • Wenn Sie Ihre API mit einer neuen Nebenversionsnummer neu bereitstellen, werden nachfolgende Aktivitäten in den Grafiken und Logs mit der neuen Versionsnummer gekennzeichnet. So erhalten Sie einen mit Labels versehenen Verlauf Ihrer Bereitstellungen.

  • Wenn Sie eine Version einer API entfernen, zeigen die Grafiken und Logs weiterhin Daten in dem Zeitraum an, in dem die API aktiv war.

Beispiel für API-Lebenszyklus

In diesem Abschnitt wird eine typische Entwicklung eines Dienstes beschrieben.

Version 1

Sie stellen zuerst die Version 1 des API-Dienstes "My Awesome Echo" bereit. Die API wird von my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo bereitgestellt. In den Diagrammen und Logs in Endpoints > Dienste sehen Sie den gesamten Traffic für 1.0.

Version 1.1

Ihre Kunden fordern eine neue Funktion an. Also fügen Sie in Ihrer OpenAPI-Konfigurationsdatei eine neue Methode hinzu und erhöhen den Wert im Feld info.version auf 1.1. Sie erhöhen die Nebenversionsnummer, weil der Clientcode durch diese Änderung nicht beeinträchtigt wird. Sie stellen Ihre Änderung in einer Staging-Umgebung bereit und testen sie, um sicherzustellen, dass sie funktioniert.

Als Nächstes stellen Sie die OpenAPI-Konfiguration und das API-Back-End in der Produktionsumgebung bereit. Die API wird noch von my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo bereitgestellt, aber jetzt können Aufrufer Anfragen an die neue Methode stellen. Da Sie die Schnittstelle zu den alten Methoden nicht geändert haben, müssen die Clients Ihrer Kunden nicht geändert oder neu bereitgestellt werden. Clients können wie zuvor Anfragen an die alte Methode senden.

In Endpoints > Dienste hat der bereitgestellte Traffic nun die Version 1.1. Wenn Sie einen früheren Zeitraum für die Anzeige auswählen, wird die vorherige Version in den Grafiken und Logs angezeigt, sodass Sie einen mit Labels versehenen Verlauf Ihrer Bereitstellungen erhalten.

Version 2.0

Mit der Zeit erkennen Sie, dass Sie eine nicht rückwärtskompatible Änderung an einer vorhandenen Methode vornehmen müssen. Da es wichtig ist, den Clientcode Ihres Kunden nicht zu beeinträchtigen, entscheiden Sie sich, zwei Versionen der API beizubehalten. Sie lassen die alte Methode unverändert und implementieren die neue Version der Methode. Sie erstellen eine weitere OpenAPI-Konfigurationsdatei für die Version 2.0 und konfigurieren die neue bereitzustellende Version in my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo. Ihre ursprüngliche OpenAPI-Konfigurationsdatei verweist noch auf die alte Version der Methode, während die neue OpenAPI-Konfigurationsdatei auf die neue verweist.

Sie stellen die OpenAPI-Konfigurationsdateien der Version 1 und der Version 2 gleichzeitig bereit und stellen das Back-End, das jetzt beide Versionen der Methode enthält, neu bereit. Weitere Informationen finden Sie unter API versionieren.

Nach der Bereitstellung wird in Endpoints > Dienste angezeigt, dass Sie zwei Versionen Ihrer API bereitstellen, und Sie können sehen, wie viel Traffic jede Version erhält. Ihre v1-Clients können weiterhin /v1 aufrufen, aber sie können auch /v2 aufrufen, um die neue Version der Methode zu verwenden. Wie Sie mit der Versionierung in Ihrem Back-End-Code umgehen, hängt vom verwendeten API-Framework ab. Ein Beispiel zu Servlets finden Sie in Beispiel für Endpoints und Java mit mehreren Versionen.

Version 1 deaktivieren

Wenn Ihre Clients mit der Zeit migriert werden und Sie sehen, dass sämtlicher Traffic an v1 gestoppt wurde, können Sie seine Bereitstellung beenden. Um die Version 1 Ihrer API zu entfernen, stellen Sie nur die Version 2 der OpenAPI-Konfigurationsdatei bereit und stellen Sie dann das Back-End erneut bereit. Jetzt können Sie den Code, durch den die Version 1 von Ihrem Back-End implementiert wurde, sicher entfernen. In Endpoints > Dienste werden die Verlaufsdaten von Version 1.x gespeichert.

Staging durchführen

Als Best Practice empfehlen wir, ein Staging von Aktualisierungen für Ihren Endpoints-Dienst durchzuführen, damit Sie den Dienst testen können, bevor er Ihre Kunden erreicht. Wir empfehlen außerdem, ein separates Google Cloud-Projekt für das Staging Ihres Dienstes zu erstellen, damit es von der Produktion getrennt wird. Beispielsweise werden Google-Kontingente im Allgemeinen von Ressourcen in einem Projekt gemeinsam verwendet. Wenn Sie also den Staging-Dienst in dasselbe Projekt wie den Produktionsdienst einfügen, kann z. B. eine fehlerhafte Routine in einer Schleife einen Ausfall Ihres Produktionsdienstes zur Folge haben.

Wir empfehlen, einen Google Cloud-Projektnamen zu verwenden, aus dem klar hervorgeht, dass das Projekt für das Staging bestimmt ist. Eine gängige Methode besteht darin, denselben Namen wie für das Google Cloud-Projekt für die Produktion zu verwenden, nur mit -staging am Ende. Sie können Produktionsprojekte auch durch den Zusatz -prod ergänzen, um deutlich zu machen, dass das Projekt Produktionsdienste enthält.

Dienstnamen in Google Cloud müssen eindeutig sein. Da Sie den Namen des Dienstes in der OpenAPI-Konfigurationsdatei angeben, benötigen Sie entweder separate API-Konfigurationsdateien für die Staging- und Produktionsprojekte oder müssen eine Reihe von API-Konfigurationsdateien verwenden und einen Prozess definieren. Dabei geben Sie als Dienstnamen den Namen des Projekts an, für das Sie die Bereitstellung durchführen.

Weitere Informationen