Tutorial: Publicar várias versões da sua API

APLICA-SE A: todas as camadas do Gerenciamento de API

Há situações em que é impraticável que todos os consumidores de API usem a mesma versão. Quando os consumidores estão prontos para atualizar para uma versão mais recente, eles preferem uma abordagem simples e compreensível. Conforme demonstrado neste tutorial, o Gerenciamento de API do Azure dá suporte à exposição de várias versões de API para atender a essa necessidade.

Para obter informações, veja Versões e Revisões.

Neste tutorial, você aprenderá a:

Pré-requisitos

• Conheça a terminologia do Gerenciamento de API do Azure.
• Conclua o início rápido Criar uma instância do Gerenciamento de API do Azure.
• Conclua o tutorial Importar e publicar sua primeira API.

Adicionar uma nova versão

1. No portal do Azure, navegue até a instância do Gerenciamento de API.
2. No menu à esquerda, na seção APIs , selecione APIs.
3. Localize Swagger Petstore – OpenAPI 3.0 na lista de APIs. Selecione as reticências (…) ao lado de Swagger Petstore – OpenAPI 3.0 e, em seguida, selecione Adicionar versão. Você adicionará valores à janela resultante na próxima seção.

Escolher um esquema de controle de versão

No Gerenciamento de API, você escolhe 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, Path é usado como o esquema de versionamento.

Na janela Criar uma nova API como uma versão , insira os valores da tabela a seguir. Depois, selecione Criar para criar a versão.

Depois de criar a versão, ela aparece em Swagger Petstore – OpenAPI 3.0 na lista de API. Agora você vê duas APIs: Original e v1:

Editar uma versão

Depois de adicionar a versão, você pode editá-la e configurá-la como uma API separada da original. As alterações em uma versão não afetam outra (por exemplo, se você adicionar ou remover operações de API ou editar a especificação OpenAPI). Para saber mais, veja Editar uma API.

Adicionar a versão a um produto

Para que os chamadores vejam a nova versão, ela deve ser adicionada a um produto. Se você ainda não adicionou a versão a um produto, poderá fazê-lo a qualquer momento.

Para adicionar a versão a um produto:

1. No portal do Azure, navegue até a instância do Gerenciamento de API.
2. Em APIs no painel esquerdo, selecione Produtos.
3. Selecione o produto e selecione APIs no painel esquerdo.
4. Selecione + Adicionar.
5. Selecione a API.
6. 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. Se você selecionar o nome de uma API que tenha várias versões, o portal exibirá seu conjunto de versões. Você pode personalizar o nome e a descrição de um conjunto de versões.

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 Introdução ao 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 saber mais, 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 obter outras opções de entrada, consulte Autenticar no Azure usando 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 e gerenciar 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 última versão, 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 <resource-group-name> \
    --service-name <API-Management-service-name> --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 <resource-group-name> \
    --service-name <API-Management-service-name> --version-set-id <ID from the Name column>

Para obter mais informações sobre os conjuntos de versões, veja Versões no Gerenciamento de API do Azure.

Exibir a versão no portal do desenvolvedor

Se você usar o portal do desenvolvedor, poderá ver as versões da API lá.

1. Selecione o portal do Desenvolvedor na parte superior da janela.
2. Selecione APIs e depois Swagger Petstore.
3. Você verá uma lista suspensa que mostra várias versões ao lado do nome da API.
4. Selecione v1.
5. Observe a URL de Solicitação da primeira operação na lista. Ela mostra que o caminho da URL da API inclui v1.

Próxima etapa

Vá para o próximo tutorial: