Compute Engine-Versionsleitfaden: APIs, Clientbibliotheken und Tools

In diesem Leitfaden wird beschrieben, wie Compute Engine Versionen für REST APIs, Clientbibliotheken und das gcloud-Befehlszeilentool verwaltet. Darin wird der Unterschied zwischen der channelbasierten Versionierung (Channel-Based Versioning, CBV) und der schnittstellenbasierten Versionierung (Interface-Based Versioning, IBV) beschrieben, wobei der Schwerpunkt hauptsächlich auf der IBV liegt.

Hinweis

  • Richten Sie die Authentifizierung ein, falls Sie dies noch nicht getan haben. Bei der Authentifizierung wird Ihre Identität für den Zugriff auf Google Cloud Dienste und APIs überprüft. Zur Ausführung von Code oder Beispielen aus einer lokalen Entwicklungsumgebung können Sie sich so bei Compute Engine authentifizieren:

    Wählen Sie den Tab für die geplante Verwendung der Beispiele auf dieser Seite aus:

    Console

    Wenn Sie über die Google Cloud Console auf Google Cloud -Dienste und -APIs zugreifen, müssen Sie die Authentifizierung nicht einrichten.

    gcloud

    1. Installieren Sie die Google Cloud CLI. Initialisieren Sie die Google Cloud CLI nach der Installation mit dem folgenden Befehl: 

      gcloud init

      Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

  • Legen Sie eine Standardregion und -zone fest.

    • REST

    Wenn Sie die REST API-Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung verwenden möchten, verwenden Sie die Anmeldedaten, die Sie der gcloud CLI bereitstellen.

      Installieren Sie die Google Cloud CLI.

      Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

    Weitere Informationen finden Sie in der Dokumentation zur Google Cloud -Authentifizierung unter Für die Verwendung von REST authentifizieren.

Kanalbasierte und schnittstellenbasierte Versionsverwaltung

Die Compute Engine API unterstützt zwei Versionierungsschemas: channel-based versioning (CBV) und interface-based versioning (IBV).

  • Bei der channelbasierten Versionsverwaltung sind Releases langlebig und erhalten In-Place-Updates. Compute Engine unterstützt die Kanäle „v1“, „Beta“ und „Alpha“.

  • Beim interfacebasierten Versioning werden einzelne Schnittstellen, Methoden und Ressourcen versioniert und können inkrementell und unabhängig weiterentwickelt werden.

Der IBV hat Vorrang vor dem CBV. Bestehende Implementierungen von CBV sind jedoch nicht von der Einführung von IBV und von neuen Versionen betroffen. Sie können CBV weiterhin verwenden, wenn Sie die vorhandene API-Version beibehalten möchten.

Mit IBV können Sie darauf vertrauen, dass das Verhalten der API sowie ihre Anfrage- und Antwortnutzlast einer bestimmten API-Version entsprechen. Sie verwenden IBV, indem Sie in Ihrer Anfrage eine API-Version angeben, entweder mit einem Abfrageparameter oder einem Header. Weitere Informationen finden Sie unter API-Anfrage erstellen.

Die Verwendung von IBV bietet folgende Vorteile:

  • Höhere Stabilität:IBV schützt laufende Anwendungen vor Änderungen, da Sie die API-Version angeben können, mit der der Dienst antworten muss.
  • Kontrolle über die Übernahme von Änderungen:Mit IBV können Sie auswählen, welche Version für Ihre Anfrage verwendet wird. So können Sie selbst entscheiden, wann Sie auf neue Dienstfunktionen umstellen.

Weitere Informationen zu Versionsverwaltungsstrategien finden Sie im API-Verbesserungsvorschlag 185.

Schnittstellenbasierte Versionsrichtlinie

Jede Version der Compute Engine IBV API ist eine Sammlung von Schnittstellenänderungen, die dieselbe Dienstversion haben, auch wenn sich Schnittstellen unabhängig voneinander ändern können.

Die Compute Engine IBV API unterstützt stabile Versionen und Vorschauversionen.

Stabile Versionen

Die meisten API-Releases sind stabile Versionen. Stabile Versionen sind streng kompatibel, wie in AIP-180 definiert. Das bedeutet, dass neuere stabile Releases derselben Version keine vorhandenen Funktionen beeinträchtigen oder Code-Neuschreibungen erfordern.

Compute Engine identifiziert stabile API-Versionen anhand von Standarddatumsangaben im Format YYYY-MM-DD (z. B. 2026-09-01). Spätere Datumsangaben weisen auf neuere Releases hin.

Compute Engine unterstützt stabile Versionen über lange Zeiträume hinweg, damit Ihre Produktionssysteme zuverlässig und ohne Unterbrechungen funktionieren. Für die meisten Anwendungen benötigen Sie nur eine einzige stabile Version, um Ihre täglichen Aufgaben zu erledigen.

Vorabversionen

Compute Engine kann Vorschauversionen veröffentlichen, um frühzeitig Nutzerfeedback zu neuen Funktionen zu erhalten. Bei Vorschauversionen wird dem Datum ein -preview-Tag angehängt, z. B. 2026-10-01-preview.

Vorabversionen enthalten alle Funktionen der letzten stabilen Version sowie neu hinzugefügte experimentelle Funktionen. Beachten Sie bei der Verwendung von Vorabversionen Folgendes:

  • Vorabfunktionen garantieren keine Kompatibilität mit früheren oder zukünftigen Releases.
  • Wir raten davon ab, Vorabversionen für geschäftskritische Produktionsumgebungen zu verwenden.
  • Wir können Vorabfunktionen ändern, optimieren oder entfernen, wenn wir sie in eine stabile Version überführen.

Verwenden Sie Vorabversionen, wenn Sie neue Funktionen ausprobieren möchten, und planen Sie, Ihren Code zu aktualisieren, wenn eine stabile Version veröffentlicht wird.

API-Version in der Anfrage angeben

Wenn Sie API-Aufrufe mit IBV ausführen möchten, müssen Sie in Ihren Anfragen eine Zielversion angeben. Dazu verwenden Sie entweder einen Abfrageparameter oder einen Header. Beispiele für das Senden von API-Anfragen finden Sie unter API-Anfrage erstellen.

Cloud-Clientbibliotheken

Mit Cloud-Clientbibliotheken müssen Sie keine REST-Rohaufrufe mehr erstellen und parsen. Jede Bibliotheksversion ist direkt mit einer bestimmten datumsbasierten API-Version verknüpft.

Wenn Sie auf neue Funktionen zugreifen möchten, aktualisieren Sie Ihr Cloud-Clientbibliotheken-Paket auf die neueste Version. Wir veröffentlichen aktualisierte Cloud-Clientbibliotheken zusammen mit neuen stabilen und Preview-API-Releases.

Wir empfehlen, Produktionsanwendungen mit stabilen Cloud-Clientbibliotheken auszuführen und Preview-Bibliotheken auf Testumgebungen zu beschränken.

Google Cloud CLI (gcloud)

Mit der gcloud CLI können Sie Compute Engine-Ressourcen verwalten, ohne einzelne REST-Endpunkte manuell verfolgen zu müssen.

In der gcloud-CLI werden Befehle in zwei Kategorien unterteilt:

  • Stabile Befehle:Standardbefehle (z. B. gcloud compute instances create) sind auf stabile API-Versionen ausgerichtet. Diese Befehle werden vollständig unterstützt, sind vorhersehbar und werden für Produktionsskripts empfohlen.
  • Vorabbefehle:Bei Early Access-Funktionen wird die Gruppe gcloud preview verwendet, z. B. gcloud preview compute .... Bei diesen Befehlen wird eine kurze Warnung angezeigt, da sich Verträge vor der endgültigen Veröffentlichung ändern können.

Terraform

Der Google Cloud Terraform-Provider abstrahiert die API-Versionsverwaltung und verwaltet die zugrunde liegenden API-Interaktionen. In Terraform-Konfigurationen werden keine manuellen Einstellungen für Versionsheader verfügbar gemacht oder benötigt.

Wenn Sie auf neue Funktionen zugreifen möchten, aktualisieren Sie Ihren Google Cloud Terraform-Provider auf die aktuelle Version. Verwenden Sie für Vorschaufunktionen den google-beta-Anbieter.

Häufig gestellte Fragen

In diesem Abschnitt finden Sie Antworten auf häufig gestellte Fragen zur Versionsverwaltung der Compute Engine API.

  • Muss ich von v1 (CBV) zu IBV migrieren?

    Nein. Bestehende CBV v1-API-Anfragen funktionieren weiterhin wie bisher. Sie können jedoch nicht auf neue Funktionen zugreifen, die in der IBV API verfügbar sind.

  • Wie lange wird eine IBV-API-Version unterstützt?

    Stabile Versionen werden gemäß der standardmäßigen Google CloudRichtlinie zur Einstellung von Produkten und Diensten auf unbestimmte Zeit beibehalten.

  • Wie oft werden neue IBV API-Versionen veröffentlicht?

    Neue IBV API-Versionen sind für vierteljährliche Releases geplant. Vorabversionen können jederzeit veröffentlicht werden.

  • Muss ich etwas in der Google Cloud Console aktivieren?

    Nein, die IBV API ist standardmäßig mit der Compute Engine API aktiviert.

  • Was passiert, wenn ich in meinem Antrag keine Version angebe?

    Ihre Anfrage wird standardmäßig an den CBV v1-Endpunkt gesendet.

  • Wo finde ich die API-Version in Cloud-Audit-Logeinträgen?

    Die API-Version wird in protoPayload.requestMetadata.callerSuppliedUserAgent und in den Anfrageheadern oder ‑parametern protokolliert.

Nächste Schritte

Weitere Informationen zur Compute Engine API finden Sie in den folgenden Dokumenten: