Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
OpenAPI | gRPC
Nesta página, você encontra procedimentos detalhados de configuração e implantação para alterar o número de versão da sua API. O procedimento que você verá depende se as alterações na sua API são compatíveis com versões anteriores.
Ao fazer alterações na API que sejam compatíveis com versões anteriores do código do cliente atual, como prática recomendada, incremente o número da versão secundária da API antes de implantar a nova versão. Ainda que o Cloud Endpoints execute somente uma versão secundária de uma API por vez, os gráficos e os registros em Endpoints > Serviços exibem o número da versão. Ao incrementar o número da versão secundária antes de implantá-la, os gráficos e registros fornecem um histórico rotulado das implantações.
Incrementar o número inferior da versão:
Em openapi.yaml, incremente o número da versão secundária do campo info.version. Por exemplo, se a versão atual for 1.1, defina info.version como 1.2:
info:description:"A simple Cloud Endpoints API example."title:"Endpoints Example"version:"1.2"host:"echo-api.endpoints.example-project-12345.cloud.goog"
Use a CLI do Google Cloud para implantar a configuração da API:
gcloud endpoints services deploy openapi.yaml
Implante o backend da API com a ID de configuração retornada da etapa anterior. Consulte os detalhes em Como implantar o back-end da API.
Alterações incompatíveis com versões anteriores
Quando você faz alterações na API que quebram o código de cliente dos seus clientes, a prática recomendada é incrementar o número da versão principal da API.
Os endpoints podem executar mais de uma versão principal de uma API ao mesmo tempo. Com as duas versões da API, os clientes podem escolher que versão usar e quando migrar para uma nova.
Para executar a versão nova e a atual de uma API ao mesmo tempo:
Crie arquivos de configuração do OpenAPI separados para cada versão a ser exibida. Este procedimento usa os nomes de arquivo openapi-v1.yaml e openapi-v2.yaml para fins de exemplo.
Copie o conteúdo de openapi-v1.yaml para openapi-v2.yaml.
Em openapi-v1.yaml, configure o seguinte:
Defina o campo info.version como o número da versão existente.
Deixe o campo basePath como está
Por exemplo:
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"
Em openapi-v2.yaml, configure o seguinte:
Faça alterações incompatíveis com versões anteriores.
Defina o campo info.version como o novo número de versão.
Defina o campo basePath para incluir o novo número da versão principal.
Remova a seção x-google-endpoints. Esta seção é necessária se você
quiser especificar o endereço IP do DNS ou a sinalização allowCors. Ao implantar duas
versões da API com dois arquivos de configuração yaml, apenas um deles pode ter
x-google-endpoints, mas a configuração será aplicada às duas versões.
Exemplo:
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"
Use a Google Cloud CLI para implantar os dois arquivos de configuração da API:
Implante um único back-end que atenda às duas versões da API usando a ID de configuração retornada da etapa anterior. Consulte os detalhes em Como implantar o back-end da API.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 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)"]]
