API-Versionierung handhaben

Auf dieser Seite wird erläutert, wie Sie die API versionieren und mehrere Versionen bereitstellen.

Empfehlungen für die Verwaltung von API-Versionen

So verwalten Sie Ihre API-Versionen effizient:

  • Wenn Sie eine inkrementelle abwärtskompatible Änderung vornehmen möchten, behalten Sie die API-Version bei und stellen Sie sie über der vorhandenen API bereit.
  • Wenn Sie eine nicht abwärtskompatible Änderung an der API vornehmen möchten, erhöhen Sie die API-Version.
  • Erhöhen Sie für zusätzlichen Schutz auch die Version der App Engine-Anwendung und stellen Sie dann die neue API-Version für diese neue App Engine-Anwendungsversion bereit. So können Sie die Flexibilität von App Engine nutzen und schnell zwischen App Engine-Versionen wechseln. Falls unerwartete Probleme auftreten, stellen Sie einfach eine der alten funktionierenden Versionen bereit.

In der folgenden Tabelle werden die Back-End-API-Versionen mit verschiedenen App Engine-Anwendungsversionen kaskadiert.

Anwendungsversion Back-End-API-Version
1.
  • v1 --> v1 (2) --> v1 (n)
2.
  • v1 (n)
  • v2 --> v2 (2) --> v2 (n)
3.
  • v1 (n)
  • v2 (n)
  • v3 --> v3 (2) --> v3 (n)

Wie in der Tabelle dargestellt, werden inkrementelle abwärtskompatible Aktualisierungen auf v1 der API durchgeführt, die jeweils die vorherige Version überschreiben. Wenn grundlegende Änderungen eingeführt werden, wird die API-Version auf v2 erhöht und in einer neuen App Engine-Anwendungsversion bereitgestellt. Dadurch können Sie bei Bedarf wieder zur vorherigen Anwendungsversion wechseln.

Beachten Sie, dass die Anwendungsversion 2 in der Tabelle sowohl die letzte v1-Version als auch die neue v2-Version der API unterstützt. Wenn Sie den vorhandenen v1-Code nicht aus Ihrem Projekt löschen, werden bei der Bereitstellung des Projekts sowohl v2 als auch vl (n) der API in Version 2 Ihrer Anwendung bereitgestellt.

Mehrere Anwendungsversionen bereitstellen

Die Bereitstellung Ihrer Backend-API findet unter der Projekt-ID des Google Cloud-Projekts statt, das Sie für die API erstellt haben. Außerdem müssen Sie die App Engine-Version für die Bereitstellung angeben. Sie legen die App Engine-Version im <version>-Element der Datei /WEB-INF/appengine-web.xml fest. Die App Engine-App-Version entspricht nicht der Back-End-API Versionsnummer, die Sie im Attribut version der @Api angeben .

Api-Versionen

Wie in der vorherigen Abbildung zu sehen ist, können Sie mehrere API-Versionen für dieselbe App Engine-Version bereitstellen. Außerdem können Sie für eine Anwendung mehrere App Engine-Versionen verwenden.

Zugriff auf die für eine Bereitstellungsversion verwendeten API-Versionen

Die erste App Engine-Version, für die Sie die API bereitstellen, ist die Bereitstellungsversion. Diese Version wird unter der URL http://YOUR_PROJECT_ID.appspot.com ausgeführt, wobei YOUR_PROJECT_ID für Ihre Google Cloud-Projekt-ID steht. Mit dieser URL können Sie auf alle API-Versionen zugreifen, die für diese App Engine-Anwendungsversion bereitgestellt sind.

Die Bereitstellungsversion bleibt gleich, bis Sie sie in der Google Cloud Console ändern.

Auf die für eine Nicht-Bereitstellungs-Anwendungsversion verwendeten API-Versionen zugreifen

Wenn Sie auf API-Versionen zugreifen müssen, die für die aktuell bereitgestellte App Engine-Version nicht eingesetzt werden, verwenden Sie eine versionsspezifische URL, die in etwa so aussieht:

https://VERSION-dot-YOUR_PROJECT_ID.appspot.com

Ersetzen Sie VERSION durch Ihre App Engine-Version und YOUR_PROJECT_ID durch Ihre Google Cloud-Projekt-ID. Beispiel: Ihre App Engine-Bereitstellungsversion lautet 1, Sie möchten jedoch auf eine API-Version zugreifen, die in Version 2 bereitgestellt ist. Verwenden Sie in diesem Fall die URL https://2-dot-YOUR_PROJECT_ID.appspot.com.

Weitere Informationen finden Sie in der App Engine-Dokumentation.

Auf API-Versionen zugreifen, die für Nicht-Bereitstellungsdienste (ehemals Module) bereitgestellt werden

Wenn Sie auf API-Versionen zugreifen müssen, die nicht für den standardmäßigen App Engine-Dienst bereitgestellt sind, können Sie eine versionsspezifische URL mit der dot-Syntax verwenden:

https://SERVICE-NAME-dot-YOUR_PROJECT_ID.appspot.com/_ah/api/...

Weitere Informationen finden Sie in der App Engine-Dokumentation.