Guia de controle de versões do Compute Engine: APIs, bibliotecas de cliente e ferramentas

Este guia explica como o Compute Engine gerencia versões em APIs REST, bibliotecas de cliente e a ferramenta de linha de comando gcloud. Ele descreve a diferença entre o controle de versões baseado em canais (CBV) e o controle de versões baseado em interfaces (IBV), com foco principal no último.

Antes de começar

  • Configure a autenticação, caso ainda não tenha feito isso. Com isso, você confirma sua identidade para acesso a serviços e APIs do Google Cloud . Para executar códigos ou amostras de um ambiente de desenvolvimento local, autentique-se no Compute Engine selecionando uma das seguintes opções:

    Selecione a guia para como planeja usar as amostras nesta página:

    Console

    Quando você usa o console Google Cloud para acessar os serviços e as APIs Google Cloud , não é necessário configurar a autenticação.

    gcloud

    1. Instale a CLI do Google Cloud. Após a instalação, inicialize a Google Cloud CLI executando o seguinte comando: 

      gcloud init

      Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  • Defina uma região e uma zona padrão.

    • REST

    Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

      Instale a CLI do Google Cloud.

      Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

    Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

Controle de versões com base em canais e interfaces

A API Compute Engine é compatível com dois esquemas de controle de versões: controle de versões baseado em canais (CBV) e controle de versões baseado em interfaces (IBV).

  • No controle de versões com base em canais, as versões são de longa duração e recebem atualizações no local. O Compute Engine oferece suporte aos canais v1, Beta e Alfa.

  • Na versão baseada em interface, interfaces, métodos e recursos individuais são versionados e podem evoluir de forma incremental e independente.

O IBV substitui o CBV. No entanto, as implementações atuais de CBV não são afetadas pela introdução de IBV e por novas versões. Você pode continuar usando a CBV se preferir manter a versão atual da API.

A IBV ajuda a garantir que o comportamento da API e o payload de solicitação e resposta dela estejam em conformidade com uma versão pretendida da API. Para usar a IBV, especifique uma versão da API na sua solicitação usando um parâmetro de consulta ou um cabeçalho. Para mais informações, consulte Criar uma solicitação de API.

O uso da IBV oferece os seguintes benefícios:

  • Maior estabilidade:a IBV protege os aplicativos em execução contra mudanças permitindo que você indique a versão da API com que o serviço precisa responder.
  • Controle sobre a adoção de mudanças:com a IBV, você escolhe qual versão atende à sua solicitação. Assim, você pode fazer upgrade para novos recursos do serviço na sua própria programação.

Para mais informações sobre estratégias de controle de versões, consulte a proposta de melhoria da API 185.

Política de controle de versões com base em interface

Cada lançamento da API IBV do Compute Engine é uma coleção de mudanças de interface que compartilham a mesma versão do serviço, mesmo que as interfaces mudem de versão de forma independente.

A API IBV do Compute Engine oferece suporte a versões estáveis e de prévia.

Versões estáveis

A maioria dos lançamentos de API são versões estáveis. As versões estáveis mantêm a compatibilidade estrita, conforme definido na AIP-180. Isso significa que novas versões estáveis da mesma versão não interrompem a funcionalidade atual nem exigem a reescrita do código.

O Compute Engine identifica versões estáveis da API usando datas padrão no formato YYYY-MM-DD (como 2026-09-01). Datas posteriores indicam versões mais recentes.

O Compute Engine oferece suporte a versões estáveis por longos períodos para que seus sistemas de produção permaneçam confiáveis e ininterruptos. Para a maioria dos aplicativos, basta usar uma única versão estável para realizar suas tarefas diárias.

Versões de visualização

O Compute Engine pode lançar versões de prévia para coletar feedback antecipado dos usuários sobre novos recursos. As prévias de lançamento acrescentam uma tag -preview à data (como 2026-10-01-preview).

As versões de prévia incluem todos os recursos da versão estável mais recente, além de novos recursos experimentais. Ao usar versões de prévia, tenha em mente o seguinte:

  • Os recursos de prévia não garantem compatibilidade com versões anteriores ou futuras.
  • Não recomendamos o uso de versões de pré-lançamento em ambientes de produção de missão crítica.
  • Podemos mudar, refinar ou remover recursos de prévia enquanto os promovemos para uma versão estável.

Use versões de prévia quando quiser testar novos recursos e planeje atualizar seu código quando uma versão estável for lançada.

Especificar uma versão da API na solicitação

Para fazer chamadas de API usando o IBV, suas solicitações especificam uma versão de destino usando um parâmetro de consulta ou um cabeçalho. Para exemplos de como fazer solicitações de API, consulte Criar uma solicitação de API.

Bibliotecas de cliente do Cloud

As bibliotecas de cliente do Cloud removem o peso de criar e analisar chamadas REST brutas. Cada lançamento de biblioteca se conecta diretamente a uma versão específica da API baseada em data.

Para acessar novos recursos, atualize o pacote das bibliotecas de cliente do Cloud para a versão mais recente. Publicamos bibliotecas de cliente do Cloud atualizadas junto com novas versões estáveis e de prévia das APIs.

Recomendamos executar aplicativos de produção em bibliotecas de cliente do Cloud estáveis e isolar as bibliotecas de prévia em ambientes de teste.

Google Cloud CLI (gcloud)

Com a CLI gcloud, é possível gerenciar recursos do Compute Engine sem precisar rastrear endpoints REST individuais manualmente.

A CLI gcloud divide os comandos em duas categorias:

  • Comandos estáveis:comandos padrão (como gcloud compute instances create) têm como destino versões estáveis da API. Esses comandos são totalmente compatíveis, previsíveis e recomendados para scripts de produção.
  • Comandos de prévia:os recursos de acesso antecipado usam o grupo gcloud preview (como gcloud preview compute ...). Esses comandos mostram um breve aviso porque os contratos podem mudar antes do lançamento final.

Terraform

O provedor do Terraform Google Cloud abstrai o controle de versões da API e gerencia as interações da API subjacente. As configurações do Terraform não expõem nem exigem configurações manuais de cabeçalho de versão.

Para acessar novos recursos, atualize seu Google Cloud provedor do Terraform para a versão mais recente. Para recursos de visualização, use o provedor google-beta.

Perguntas frequentes

Esta seção responde a perguntas frequentes sobre o controle de versões da API Compute Engine.

  • Preciso migrar da v1 (CBV) para a IBV?

    Não, as solicitações da API CBV v1 continuam funcionando como antes. No entanto, não será possível acessar os novos recursos disponíveis na API IBV.

  • Por quanto tempo uma versão da API IBV vai ter suporte?

    As versões estáveis são mantidas indefinidamente de acordo com a política de descontinuação padrão Google Cloud.

  • Com que frequência novas versões da API IBV são lançadas?

    Novas versões da API IBV estão planejadas para lançamentos trimestrais. As versões de prévia podem ser lançadas a qualquer momento.

  • Preciso ativar alguma coisa no console do Google Cloud ?

    Não, a API IBV é ativada por padrão com a API Compute Engine.

  • O que acontece se eu não especificar uma versão na minha solicitação?

    Sua solicitação usa o endpoint da CBV v1 por padrão.

  • Onde posso encontrar a versão da API nas entradas dos Registros de auditoria do Cloud?

    A versão da API é registrada em protoPayload.requestMetadata.callerSuppliedUserAgent e nos cabeçalhos ou parâmetros de consulta da solicitação.

A seguir

Para saber mais sobre a API Compute Engine, leia os seguintes documentos: