Política de controle de versão para serviços do Azure, SDKs e ferramentas da CLI
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 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 controlar a versão das APIs REST do Azure. Embora as equipes do Azure façam todos os esforços para aderir a essa política, podem ocorrer desvios ocasionalmente.
Controle de versão de serviço
Cada versão publicada de uma API é identificada por um valor de data no YYYY-MM-DD formato, chamado de 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 parâmetro de api-version cadeia de caracteres de consulta na URL. Por exemplo: https://management.azure.com/subscriptions?api-version=2020-01-01. Os SDKs e as ferramentas do cliente incluem o api-version valor automaticamente. Para obter mais considerações, consulte a seção SDKs do cliente e versões de serviço mais adiante neste artigo.
Na maioria dos cenários, um cliente de serviço só precisará interagir com uma única versão de um serviço para acessar todas as funcionalidades necessárias.
As versões de serviço estáveis geralmente permanecem disponíveis e com suporte por muitos anos, mesmo quando as 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 no 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 nenhuma alteração de código para manter a exatidão ou a funcionalidade existente.
Versões de alteração interruptiva
Uma versão de alteração significativa de um serviço não é compatível com versões anteriores. A adoção de uma versão de alteração significativa 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 interruptiva são raras, anunciadas por meio da documentação e normalmente são precedidas pela publicação de uma versão prévia. A publicação de uma versão de alteração significativa 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 significativa. 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 orientados por IA podem ter uma disponibilidade mínima reduzida de um ano. Cada serviço publicará sua política de alterações significativas.
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 significativa devido a isso será vinculada à política do fornecedor do componente, mostrando a data em que o componente não é mais compatível.
Versões prévias
Ocasionalmente, a Microsoft publica uma versão prévia 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 seus api-version - por exemplo, 2022-07-07-preview.
A menos que explicitamente destinado a introduzir uma alteração significativa 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 prévias, um serviço pode interromper 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 for disponibilizada, as versões prévias existentes poderão ficar indisponíveis em até 90 dias a partir da disponibilidade da nova versão. Use versões prévias somente em situações em que você está desenvolvendo ativamente em novos recursos de serviço e está preparado para adotar uma nova versão não prévia logo após o lançamento. Se alguns recursos de uma versão prévia forem lançados em uma nova versão estável, os recursos restantes ainda em versão prévia normalmente serão publicados em uma nova versão prévia.
SDKs de cliente e versões de serviço
Os SDKs do Azure visam eliminar o controle de versão do 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 da biblioteca de cliente tem como destino uma única versão do serviço do qual 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 de clientes usada pelo aplicativo. Novas versões estáveis de serviços são acompanhadas por novas versões pontuais de bibliotecas de cliente. Para novas versões de alteração significativa, novas bibliotecas de cliente são publicadas como versões de lançamento pontual ou versões de lançamento principal. O tipo de versão depende da natureza da alteração do serviço e da maneira como a biblioteca é capaz de acomodá-la. Somente bibliotecas de cliente de versão beta usam versões de serviço de visualização.
As bibliotecas de cliente do SDK dão 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ê usar esse 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 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 Preview rótulo e emitirão um aviso indicando suporte limitado e possíveis alterações em versões futuras da ferramenta.