Share via

Política de controle de versão para serviços, SDKs e ferramentas de CLI do Azure

  • Artigo

A maioria dos serviços do Azure permite controlar e gerenciar programaticamente seus recursos com APIs REST. Os serviços evoluem por meio de novas versões publicadas de suas APIs com diferentes contratos que adicionam novos recursos e/ou modificam seus comportamentos.

Este artigo descreve a política que as equipes de serviço, SDK e CLI do Azure usam para versionar as APIs REST do Azure. Embora as equipas do Azure façam todos os esforços para aderir a esta política, ocasionalmente podem ocorrer desvios.

Controle de versão do serviço

Cada versão publicada de uma API é identificada por um valor de data no YYYY-MM-DD formato, chamado api-version. As versões mais recentes têm datas posteriores.

Todas as operações de API exigem que os clientes especifiquem uma versão válida da API para o serviço por meio do api-version parâmetro de cadeia de caracteres de consulta na URL. Por exemplo: https://management.azure.com/subscriptions?api-version=2020-01-01. SDKs e ferramentas de cliente incluem o api-version valor automaticamente. Para obter mais considerações, consulte a seção SDKs de cliente e versões de serviço mais adiante neste artigo.

Normalmente, as versões de serviço publicadas permanecem disponíveis e suportadas por muitos anos, mesmo quando versões mais recentes se tornam disponíveis. Na maioria dos casos, a única vez que você deve adotar uma nova versão de serviço dentro do código existente é aproveitar os novos recursos.

Versões estáveis

A maioria das versões de serviço publicadas são versões estáveis. As versões estáveis são compatíveis com versões anteriores, o que significa que qualquer código que você escreva que dependa de uma versão de um serviço pode adotar uma versão estável mais recente sem exigir nenhuma alteração de código para manter a correção ou a funcionalidade existente.

Quebrando versões de mudança

Uma versão de alteração de quebra de um serviço não é compatível com versões anteriores. A adoção de uma versão de alteração de quebra no código do cliente existente pode exigir alterações de código para garantir que o cliente se comporte exatamente como se comportava ao direcionar a versão anterior.

As versões de alteração de quebra são raras, anunciadas através de documentação, e normalmente são precedidas pela publicação de uma versão de pré-visualização. A publicação de uma versão de alteração de quebra pode levar à eventual desativação de versões estáveis existentes, que permanecerão disponíveis por pelo menos três anos após o lançamento da versão de alteração de rutura. Para alterações significativas publicadas devido a problemas de segurança ou conformidade, as versões de serviço estáveis existentes podem permanecer disponíveis por um ano ou menos, dependendo da gravidade do problema.

Devido à rápida inovação e desenvolvimentos em IA, os serviços baseados em IA podem ter uma disponibilidade mínima reduzida de um ano. Cada serviço publicará sua política de alteração de quebra.

Qualquer serviço do Azure dependente de um componente que não seja da Microsoft pode reduzir sua política de suporte para corresponder à política do componente. Qualquer alteração de quebra devido a isso será vinculada à política do fornecedor do componente mostrando a data em que o componente não é mais suportado.

Versões de pré-visualização

Ocasionalmente, a Microsoft publica uma versão de pré-visualização de um serviço para recolher comentários sobre as alterações propostas e as novas funcionalidades. As versões do serviço de visualização são identificadas com o sufixo -preview em seus api-version - por exemplo, 2022-07-07-preview.

A menos que explicitamente destinado a introduzir uma mudança de rutura da versão estável anterior, as novas versões de visualização incluem todos os recursos da versão estável mais recente e adicionam novos recursos de visualização. No entanto, entre as versões de visualização, um serviço pode interromper qualquer um dos recursos de visualização recém-adicionados.

As pré-visualizações não se destinam a utilização a longo prazo. Sempre que uma nova versão estável ou de pré-visualização de um serviço estiver disponível, as versões de pré-visualização existentes poderão ficar indisponíveis no prazo de 90 dias a contar da disponibilidade da nova versão. Utilize versões de pré-visualização apenas em situações em que esteja a desenvolver ativamente novas funcionalidades de serviço e esteja preparado para adotar uma nova versão que não seja pré-visualizada logo após o seu lançamento. Se alguns recursos de uma versão de visualização forem lançados em uma nova versão estável, os recursos restantes ainda em visualização normalmente serão publicados em uma nova versão de visualização.

SDKs de cliente e versões de serviço

Os SDKs do Azure visam eliminar o controle de versão de serviço como uma preocupação ao escrever código. Cada SDK é composto por bibliotecas de cliente, uma para cada serviço, e cada versão de biblioteca de cliente tem como alvo uma única versão do serviço em que depende.

Quando você usa um SDK para acessar um serviço do Azure, aproveitar as novas versões e recursos normalmente requer a atualização da versão da biblioteca do cliente usada pelo aplicativo. Novas versões estáveis de serviços são acompanhadas por novas versões pontuais de bibliotecas cliente. Para novas versões de alteração de quebra, as novas bibliotecas de cliente são publicadas como versões de lançamento pontual ou versões de lançamento principais. O tipo de liberação depende da natureza da mudança do serviço e da forma como a biblioteca é capaz de acomodá-lo. Apenas as bibliotecas de cliente da versão beta utilizam versões de serviço de pré-visualização.

As bibliotecas de cliente SDK suportam a substituição manual da versão do serviço. Substituir a versão de serviço padrão de uma biblioteca de cliente é um cenário avançado e pode levar a um comportamento inesperado. Se você fizer uso desse recurso, teste seu aplicativo completamente para garantir que ele funcione conforme desejado.

Ferramentas de linha de comando do Azure

Assim como os SDKs, as ferramentas de linha de comando do Azure (incluindo a CLI do Azure e o Azure PowerShell) são projetadas para permitir o uso dos serviços de gerenciamento do Azure sem considerar as versões. O acesso a novos recursos de serviço geralmente requer uma nova versão de uma ferramenta. Novas versões de ferramentas compatíveis com versões anteriores são lançadas mensalmente. As versões com alterações significativas são lançadas aproximadamente duas vezes por ano, ou conforme necessário para corrigir problemas críticos de segurança.

As ferramentas de linha de comando do Azure podem ocasionalmente expor recursos de visualização. Esses comandos são marcados com um rótulo e emitirão um Preview aviso indicando suporte limitado e possíveis alterações em versões futuras da ferramenta.

Próximos passos