Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
OpenAPI | gRPC
Diese Seite enthält ausführliche Konfigurations- und Bereitstellungsanleitungen zum Ändern der Versionsnummer einer API. Welche Anleitung Sie verwenden, hängt davon ab, ob die Änderungen an der API abwärtskompatibel sind.
Wenn die neue API-Version abwärtskompatible Änderungen enthält, beispielsweise neue Felder oder Methoden, lesen Sie die Informationen unter Abwärtskompatible Änderungen.
Wenn Änderungen an einer vorhandenen Methode in der neuen API dazu führen, dass der Clientcode Ihrer Kunden nicht mehr funktioniert, lesen Sie die Informationen unter Abwärtsinkompatible Änderungen.
Wenn die Änderungen an der API mit dem vorhandenen Clientcode abwärtskompatibel sind, erhöhen Sie am besten die Nebenversionsnummer der API, bevor Sie die neue Version bereitstellen. Obwohl Cloud Endpoints nur jeweils eine Nebenversion einer API ausführt, wird die Versionsnummer dennoch in den Grafiken und Logs unter Endpoints > Dienste angezeigt. Durch Erhöhung der Nebenversionsnummer vor der Bereitstellung können Sie an den Grafiken und Logs den Verlauf Ihrer Bereitstellungen ablesen.
So erhöhen Sie die Nebenversionsnummer:
Erhöhen Sie in openapi.yaml die Nebenversionsnummer des Feldes info.version. Beispiel: Wenn die aktuelle Version 1.1 lautet, legen Sie info.version auf 1.2 fest:
info:description:"A simple Cloud Endpoints API example."title:"Endpoints Example"version:"1.2"host:"echo-api.endpoints.example-project-12345.cloud.goog"
Stellen Sie die API-Konfiguration mit der Google Cloud CLI bereit:
gcloud endpoints services deploy openapi.yaml
Stellen Sie das API-Backend mithilfe der Konfigurations-ID bereit, die im vorherigen Schritt zurückgegeben wurde. Weitere Informationen finden Sie unter API-Backend bereitstellen.
Abwärtsinkompatible Änderungen
Wenn die Änderungen an der API nicht mit dem Clientcode des Kunden kompatibel sind, erhöhen Sie am besten die Hauptversionsnummer der API.
In Endpoints können mehrere Hauptversionen einer API gleichzeitig ausgeführt werden. Wenn Sie beide Versionen der API anbieten, können Kunden die gewünschte Version auswählen und selbst entscheiden, wann sie zur neuen Version migrieren.
So führen Sie die vorhandene Version und neue Versionen einer API gleichzeitig aus:
Erstellen Sie separate OpenAPI-Konfigurationsdateien für jede Version, die Sie bereitstellen müssen. Bei diesem Vorgang werden die Dateinamen openapi-v1.yaml und openapi-v2.yaml zu Beispielzwecken verwendet.
Kopieren Sie den Inhalt von openapi-v1.yaml in openapi-v2.yaml.
Konfigurieren Sie in openapi-v1.yaml Folgendes:
Legen Sie das Feld info.version auf die vorhandene Versionsnummer fest.
Ändern Sie das Feld basePath nicht.
Beispiel:
info:description:"A simple Cloud Endpoints API example."title:"Endpoints Example"version:"1.1"host:"echo-api.endpoints.example-project-12345.cloud.goog"basePath:"/v1"
Konfigurieren Sie in openapi-v2.yaml Folgendes:
Nicht abwärtskompatible Änderungen vornehmen
Legen Sie das Feld info.version auf die neue Versionsnummer fest.
Geben Sie im Feld basePath zusätzlich die neue Hauptversionsnummer an.
Entfernen Sie den Abschnitt x-google-endpoints. Dieser Abschnitt ist erforderlich, wenn Sie die DNS-IP-Adresse oder das Flag allowCors angeben möchten. Wenn Sie zwei Versionen der API mit zwei yaml-Konfigurationsdateien bereitstellen, kann nur eine davon x-google-endpoints haben. Die Konfiguration gilt jedoch für beide Versionen.
Beispiel:
info:description:"A simple Google Cloud Endpoints API example."title:"Endpoints Example"version:"2.0"host:"echo-api.endpoints.example-project-12345.cloud.goog"basePath:"/v2"
Stellen Sie beide API-Konfigurationsdateien mit der Google Cloud CLI bereit:
Stellen Sie nur ein Backend bereit, das beide Versionen der API bedient. Verwenden Sie dazu die Konfigurations-ID, die im vorherigen Schritt zurückgegeben wurde. Weitere Informationen finden Sie unter API-Backend bereitstellen.
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-09-04 (UTC)."],[[["\u003cp\u003eThis document outlines procedures for updating API versions, differentiating between backwards-compatible and backwards-incompatible changes.\u003c/p\u003e\n"],["\u003cp\u003eFor backwards-compatible changes, it's recommended to increment the minor version number in the \u003ccode\u003einfo.version\u003c/code\u003e field of the \u003ccode\u003eopenapi.yaml\u003c/code\u003e file and then deploy using the Google Cloud CLI.\u003c/p\u003e\n"],["\u003cp\u003eWhen introducing backwards-incompatible changes, it's recommended to increment the major version number and create separate OpenAPI configuration files for each version.\u003c/p\u003e\n"],["\u003cp\u003eTo deploy multiple major versions concurrently, each version should have its own configuration file (e.g., \u003ccode\u003eopenapi-v1.yaml\u003c/code\u003e, \u003ccode\u003eopenapi-v2.yaml\u003c/code\u003e) with distinct \u003ccode\u003ebasePath\u003c/code\u003e values and the \u003ccode\u003ex-google-endpoints\u003c/code\u003e section removed from all but one configuration.\u003c/p\u003e\n"],["\u003cp\u003eAfter the deployment of the API configuration files, a single backend must be deployed that services both versions of the API.\u003c/p\u003e\n"]]],[],null,["# Versioning an API\n\nOpenAPI \\| gRPC\n\n\u003cbr /\u003e\n\nThis page provides detailed configuration and deployment procedures for changing\nthe version number of your API. The procedure that you use depends on whether\nthe changes to your API are backwards compatible.\n\n- If your new API version has backwards-compatible changes, such as adding new fields or methods, see [Backwards-compatible changes](#backwards-compatible).\n- If your new API has changes to an existing method that breaks your customers' client code, see [Backwards-incompatible changes](#backwards-incompatible).\n\nFor additional information and best practices, see\n[API lifecycle management](/endpoints/docs/openapi/lifecycle-management).\n\nBackwards-compatible changes\n----------------------------\n\nWhen you make changes to your API that are backwards compatible with\nexisting client code, as a best practice, increment the minor version number of\nyour API before you deploy the new version. Although Cloud Endpoints runs only\none minor version of an API at a time, the graphs and logs in\n**Endpoints** \\\u003e **Services** display the version number. By incrementing the\nminor version number before you deploy, the graphs and logs provide a labeled\nhistory of your deployments.\n\nTo increment the minor version number:\n\n1. In `openapi.yaml`, increment the minor version number of the\n `info.version` field. For example, if the current version is `1.1`, set\n `info.version` to `1.2`:\n\n info:\n description: \"A simple Cloud Endpoints API example.\"\n title: \"Endpoints Example\"\n version: \"1.2\"\n host: \"echo-api.endpoints.example-project-12345.cloud.goog\"\n\n2. Use the Google Cloud CLI to deploy the API configuration:\n\n gcloud endpoints services deploy openapi.yaml\n\n3. Deploy the API backend by using the configuration ID returned from the\n previous step. For details, see\n [Deploying the API backend](/endpoints/docs/openapi/deploy-api-backend).\n\nBackwards-incompatible changes\n------------------------------\n\nWhen you make changes to your API that breaks your customers' client\ncode, as a best practice, increment the major version number of your API.\nEndpoints can run more than one major version of an API\nconcurrently. By providing both versions of the API, your customers can pick\nwhich version they want to use and control when they migrate to the new version.\n\nTo run the existing and new versions of an API concurrently:\n\n1. Create separate OpenAPI configuration files for each version you need to\n serve. This procedure uses the file names `openapi-v1.yaml` and\n `openapi-v2.yaml` for example purposes.\n\n2. Copy the contents of `openapi-v1.yaml` to `openapi-v2.yaml`.\n\n3. In `openapi-v1.yaml` configure the following:\n\n - Set the `info.version` field to the existing version number.\n - Leave the `basePath` field unchanged.\n\n For example: \n\n info:\n description: \"A simple Cloud Endpoints API example.\"\n title: \"Endpoints Example\"\n version: \"1.1\"\n host: \"echo-api.endpoints.example-project-12345.cloud.goog\"\n basePath: \"/v1\"\n\n4. In `openapi-v2.yaml` configure the following:\n\n - Make backwards-incompatible changes.\n - Set the `info.version` field to the new version number.\n - Set the `basePath` field to include the new major version number.\n - Remove the `x-google-endpoints` section. This section is needed if you want to specify DNS IP address or `allowCors` flag. When deploying two versions of the API with two yaml config files, only one of them can have `x-google-endpoints`, but its config will apply to both versions.\n\n For example: \n\n info:\n description: \"A simple Google Cloud Endpoints API example.\"\n title: \"Endpoints Example\"\n version: \"2.0\"\n host: \"echo-api.endpoints.example-project-12345.cloud.goog\"\n basePath: \"/v2\"\n\n5. Use the Google Cloud CLI to deploy both API configuration files:\n\n gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml\n\n | **Note:** Cloud Endpoints internally converts your multiple OpenAPI configuration files into a single configuration, which is identified by one configuration ID.\n6. Deploy a single backend that serves both versions of the API by using the\n configuration ID returned from the previous step. For details, see\n [Deploying the API backend](/endpoints/docs/openapi/deploy-api-backend).\n\nWhat's next\n-----------\n\n- [API lifecycle management](/endpoints/docs/openapi/lifecycle-management)\n- [Planning your Google Cloud projects](/endpoints/docs/openapi/planning-cloud-projects)"]]
