Controle de versões

Algumas APIs Business Profile estão disponíveis em mais de uma versão e canal de lançamento. A versão é o segmento do URL de solicitação que segue o nome do host, como v1 ou v1alpha. Nesta página, explicamos como as versões são numeradas, o nível de estabilidade de cada canal de lançamento e como chamar o canal Alfa.

Numeração da versão

Cada versão da API tem um número de versão principal e um sufixo de canal opcional:

  • Versão principal (v1, v2, ...): uma versão estável e em disponibilidade geral. Uma versão principal só recebe mudanças compatíveis com versões anteriores, como novos métodos, novos campos ou novos valores de tipo enumerado. As mudanças que não são compatíveis com versões anteriores são lançadas em uma nova versão principal.
  • Canal Alfa (v1alpha, v2alpha, ...): um canal de pré-lançamento de uma versão principal. Ele inclui tudo o que está na versão principal, além de recursos que ainda não estão em disponibilidade geral.

Canais de lançamento

Canal Estabilidade Índice
Disponibilidade geral (v1) Estável. As mudanças em uma versão principal são compatíveis com versões anteriores. Quando uma versão principal é descontinuada, ela permanece disponível por pelo menos 12 meses após o anúncio de descontinuação. As descontinuações e as datas de desativação são publicadas na página Cronograma de descontinuação. Recursos com disponibilidade geral.
Alfa (v1alpha) Pré-lançamento, sem compromisso de estabilidade e sem vida útil definida. Os recursos Alfa podem mudar ou ser desativados com um aviso prévio de pelo menos 30 dias. Não use recursos Alfa em integrações de produção. Tudo em v1, além de recursos que ainda não estão em disponibilidade geral.

Como os recursos se movem entre os canais

Quando um recurso passa de v1alpha para v1, ele permanece disponível em v1alpha.

Os guias e as páginas de referência de recursos disponíveis apenas no v1alpha são marcados como Alfa. Os novos recursos Alfa e em disponibilidade geral, bem como as mudanças ou remoções de recursos Alfa, são anunciados em Atualizações mais recentes e no registro de alterações de cada API.

Usar o Canal Alfa

Para chamar o canal Alfa, substitua v1 por v1alpha no URL da solicitação. Por exemplo:

GET https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}?readMask={readMask}

Os dois canais pertencem à mesma API, então eles compartilham o seguinte:

  • Ativação da API no console do Google Cloud.
  • Escopos do OAuth 2.0 e requisitos de acesso.
  • Nomes de recursos, como locations/{locationId}.
  • Cota. As solicitações para v1 e v1alpha são contabilizadas na mesma cota por projeto. Para mais detalhes, consulte Limites de cota.
  • Os dados da empresa subjacentes. As mudanças feitas em v1alpha são visíveis em v1 e vice-versa.

As bibliotecas de cliente e o diretório de APIs públicas incluem apenas v1. Para chamar v1alpha, envie solicitações REST diretamente.

Práticas recomendadas

  • Use a versão estável, como v1, para integrações de produção.
  • Use o canal Alfa, como v1alpha, para adotar novos recursos antes que eles atinjam a disponibilidade geral. Para compartilhar feedback, consulte Suporte.
  • Faça com que o cliente aceite campos e valores de tipo enumerado que ele não reconhece.
  • Antes de criar um recurso Alfa, consulte o guia e o registro de alterações para conhecer as limitações.