Tutorial: Publicar várias versões da sua API
APLICA-SE A: todas as camadas do Gerenciamento de API
Algumas vezes, é impraticável fazer com que todos os chamadores de sua API usem exatamente a mesma versão. Quando os chamadores desejam atualizar para uma versão mais recente, eles querem uma abordagem fácil de entender. Conforme mostrado neste tutorial, é possível fornecer várias versões no Gerenciamento de API do Azure.
Para obter informações, confira Versões e Revisões.
Neste tutorial, você aprenderá como:
- Adicionar uma nova versão a uma API existente
- Escolher um esquema de versão
- Adicionar a versão a um produto
- Procurar a versão no portal do desenvolvedor
Pré-requisitos
- Conheça a terminologia do Gerenciamento de API do Azure.
- Conclua o seguinte guia de início rápido: Criar uma instância do Gerenciamento de API do Azure.
- Além disso, conclua o seguinte tutorial: Importar e publicar sua primeira API.
Adicionar uma nova versão
- No portal do Azure, navegue até a instância do Gerenciamento de API.
- Selecione APIs.
- Selecione Demonstração de API de Conferência na lista de APIs.
- Selecione o menu de contexto ( ... ) ao lado de API de Conferência de Demonstração.
- Selecione Adicionar versão.
Dica
As versões também podem ser habilitadas quando você cria uma API. Na tela Adicionar API, selecione Versão desta API? .
Escolher um esquema de controle de versão
No Gerenciamento de API do Azure, escolha como os chamadores especificam a versão da API selecionando um esquema de controle de versão: caminho, cabeçalho ou cadeia de caracteres de consulta. No exemplo a seguir, o caminho é usado como o esquema de controle de versão.
Insira os valores da tabela a seguir. Depois, selecione Criar para criar sua versão.
| Configuração | Valor | Descrição |
|---|---|---|
| Nome | demo-conference-api-v1 | Nome exclusivo em sua instância do Gerenciamento de API. Como uma versão é, na verdade, uma nova API baseada na revisão de uma API, essa configuração é o nome da nova API. |
| Esquema de controle de versão | Caminho | A maneira como os chamadores especificam a versão da API. |
| Identificador de versão | v1 | Indicador específico do esquema da versão. Para Caminho, o sufixo para o caminho da URL da API. Se Cabeçalho ou Cadeia de caracteres de consulta estiver selecionado, insira um valor adicional: o nome do parâmetro de cadeia de caracteres de cabeçalho ou de consulta. Um exemplo de uso é exibido. |
| Produtos | Ilimitado | Opcionalmente, um ou mais produtos aos quais a versão da API está associada. Para publicar a API, você deve associá-la a um produto. Você também pode adicionar a versão a um produto mais tarde. |
Depois de criar a versão, ela aparecerá abaixo de API de Conferência de Demonstração na lista de APIs. Agora você verá duas APIs: Original e v1.
Observação
Se você adicionar uma versão a uma API sem controle de versão, uma Original também será criada automaticamente. Esta versão responde na URL padrão. A criação de uma versão Original garante que os chamadores existentes não sejam interrompidos pelo processo de adição de uma versão. Se você criar uma API com versões habilitadas no início, uma Original não será criada.
Editar uma versão
Após adicionar a versão, é possível editá-la e configurá-la como uma API separada de uma original. As alterações em uma versão não afetam a outra. Por exemplo, adicione ou remova operações de API ou edite a especificação OpenAPI. Para saber mais, confira Editar uma API.
Adicionar a versão a um produto
Para os chamadores verem a nova versão, ela deve ser adicionada a um produto. Se ainda não adicionou a versão a um produto, você pode adicioná-la a qualquer momento.
Por exemplo, para adicionar a versão ao produto Ilimitado:
- No portal do Azure, navegue até a instância do Gerenciamento de API.
- Selecione Produtos>Ilimitado>APIs>+ Adicionar.
- Selecione API de Conferência de Demonstração, versão v1.
- Clique em Selecionar.
Usar conjuntos de versões
Quando você cria várias versões, o portal do Azure cria um conjunto de versões, que representa um conjunto de versões de uma API lógica individual. Selecione o nome de uma API que tenha várias versões. O portal do Azure exibirá o conjunto de versões dela. Você pode personalizar o Nome e a Descrição de um conjunto virtual.
Interaja diretamente com os conjuntos de versões usando a CLI do Azure:
Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.
Para ver todos os conjuntos de versões, execute o comando az apim api versionset list:
az apim api versionset list --resource-group apim-hello-world-resource-group \
--service-name apim-hello-world --output table
Quando o portal do Azure cria um conjunto de versões para você, ele atribui um nome alfanumérico, que é exibido na coluna Nome da lista. Use esse nome em outros comandos da CLI do Azure.
Para ver detalhes sobre um conjunto de versões, execute o comando az apim api versionset show:
az apim api versionset show --resource-group apim-hello-world-resource-group \
--service-name apim-hello-world --version-set-id 00000000000000000000000
Para obter mais informações sobre os conjuntos de versões, confira Versões no Gerenciamento de API do Azure.
Procurar a versão no portal do desenvolvedor
Se você experimentou o portal do desenvolvedor, poderá ver as versões da API nele.
- Selecione Portal do Desenvolvedor no menu superior.
- Selecione APIs e, depois, selecione Demonstração de API de Conferência.
- Você deverá ver uma lista suspensa com várias versões ao lado do nome da API.
- Selecione v1.
- Observe a URL Se solicitação da primeira operação na lista. Ela mostra que o caminho da URL da API inclui v1.
Próximas etapas
Neste tutorial, você aprendeu a:
- Adicionar uma nova versão a uma API existente
- Escolher um esquema de versão
- Adicionar a versão a um produto
- Procurar a versão no portal do desenvolvedor
Prosseguir para o próximo tutorial: