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

  • Artigo

A maioria dos serviços do Azure permite que você controle e gerencie programaticamente seus recursos com APIs REST. Os serviços evoluem por meio de novas versões publicadas de suas APIs com contratos diferentes 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 controle de versão das APIs REST do Azure. Embora as equipes do Azure façam todos os esforços para aderir a essa política, desvios podem ocorrer ocasionalmente.

Controle de versão de serviço

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

Todas as operações de API exigem que os clientes especifiquem uma versão de API válida 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 é para 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ê escrever que dependa de uma versão de um serviço pode adotar uma versão estável mais recente sem exigir alterações de código para manter a correção ou a funcionalidade existente.

Quebrando versões de alteração

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.

Versões de alteração de quebra são raras, anunciadas por meio de documentação e normalmente são precedidas pela publicação de uma versão de visualização. A publicação de uma versão de alteração de quebra pode levar à eventual aposentadoria 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 mudança de quebra. Para alterações de quebra 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 orientados por 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 interrupção devido a isso será vinculada à política do fornecedor do componente, mostrando a data em que o componente não é mais suportado.

Versões prévias

Ocasionalmente, a Microsoft publica uma versão de visualização de um serviço para coletar comentários sobre as alterações propostas e os novos recursos. As versões do serviço de visualização são identificadas com o sufixo -preview em suas api-version - por exemplo, 2022-07-07-preview.

A menos que explicitamente destinado a introduzir uma alteração de ruptura 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 quebrar qualquer um dos recursos de visualização recém-adicionados.

As visualizações não se destinam ao uso a longo prazo. Sempre que uma nova versão estável ou de visualização de um serviço estiver disponível, as versões de visualização existentes podem ficar indisponíveis a partir de 90 dias da disponibilidade da nova versão. Use versões de visualização apenas em situações em que você está desenvolvendo ativamente em relação a novos recursos de serviço e está preparado para adotar uma nova versão não visualizada logo após 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 de bibliotecas de cliente, uma para cada serviço, e cada versão de biblioteca de cliente destina-se a uma única versão do serviço em que confia.

Quando você usa um SDK para acessar um serviço do Azure, tirar proveito de novas versões e recursos normalmente requer a atualização da versão da biblioteca de 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 última hora, as novas bibliotecas de cliente são publicadas como versões de lançamento pontual ou versões de lançamento principal. O tipo de lançamento depende da natureza da alteração do serviço e da maneira como a biblioteca é capaz de acomodá-lo. Somente bibliotecas de cliente da versão beta usam versões de serviço de visualização.

As bibliotecas de cliente SDK oferecem suporte à 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 acontece com 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 levar em conta 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 gerarão um Preview aviso indicando suporte limitado e possíveis alterações em versões futuras da ferramenta.

Próximas etapas