Compartilhar via

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

  • Artigo

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

Captura de tela mostrando as versões da API no portal do Azure.

Pré-requisitos

Adicionar uma nova versão

  1. No portal do Azure, navegue até a instância do Gerenciamento de API.
  2. Selecione APIs.
  3. Selecione Swagger Petstore na lista de APIs.
  4. Selecione o menu de contexto (...) ao lado de Swagger Petstore.
  5. Selecione Adicionar versão.

Captura de tela mostrando o comando para adicionar a versão no menu de contexto da API no portal.

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.

Captura de tela mostrando a janela para criar uma versão no portal.

Configuração Valor Descrição
Identificador de versão v1 Indicador específico do esquema da versão. Para Caminho, o sufixo para o caminho da URL da API.
Esquema de controle de versão Caminho A maneira como os chamadores especificam a versão da API.

Se Cabeçalho ou Cadeia de caracteres de consulta estiver selecionado, insira outro valor: o nome do parâmetro de cadeia de caracteres de cabeçalho ou de consulta.

Um exemplo de uso é exibido.
Nome completo da versão da API swagger-petstore-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.
Produtos Ilimitado (fornecido em determinadas camadas de serviço) 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 Swagger Petstore na lista de APIs. Agora você verá duas APIs: Original e v1.

Captura de tela das versões listadas na API no portal.

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 as demais. 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:

  1. No portal do Azure, navegue até a instância do Gerenciamento de API.
  2. Selecione Produtos>Ilimitado>APIs>+ Adicionar.
  3. Selecione Swagger Petstore, versão v1.
  4. Clique em Selecionar.

Captura de tela da adição de versão ao produto no portal.

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:

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.

  1. Selecione Portal do Desenvolvedor no menu superior.
  2. Selecione APIs e selecione Swagger Petstore.
  3. Você deverá ver uma lista suspensa com várias versões ao lado do nome da API.
  4. Selecione v1.
  5. 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:

Personalizar o estilo das páginas do Portal do desenvolvedor