Tutorial: publicar várias versões da sua API
APLICA-SE A: Todas as camadas de gerenciamento de API
Há momentos em que é impraticável fazer com que todos os chamadores da sua API usem exatamente a mesma versão. Quando os chamadores querem atualizar para uma versão posterior, eles querem uma abordagem que seja fácil de entender. Conforme mostrado neste tutorial, é possível fornecer várias versões no Gerenciamento de API do Azure.
Para obter plano de fundo, consulte Versões & Revisões.
Neste tutorial, irá aprender a:
- Adicionar uma nova versão a uma API existente
- Escolher um esquema de versão
- Adicionar a versão a um produto
- Navegar até ao portal do programador para ver a versão
Pré-requisitos
- Conhecer a terminologia da Gestão de API do Azure.
- Conclua o guia de início rápido seguinte: Criar uma instância da Gestão de API do Azure.
- Conclua também o tutorial seguinte: Importar e publicar a sua primeira API.
Adicionar uma nova versão
- No portal do Azure, navegue até sua instância de Gerenciamento de API.
- Selecione APIs.
- Selecione Swagger Petstore na lista de APIs.
- Selecione o menu de contexto (...) ao lado de Swagger Petstore.
- Selecione Adicionar versão.
Gorjeta
As versões também podem ser habilitadas quando você cria uma nova API. Na tela Adicionar API, selecione Versão desta API?.
Escolher um esquema de versões
No Gerenciamento de API do Azure, 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 controle de versão.
Insira os valores da tabela a seguir. Em seguida, selecione Criar para criar sua versão.
| Definição | valor | Description |
|---|---|---|
| Identificador de versão | v1 | Indicador específico do esquema da versão. Para Path, 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 a opção Cabeçalho ou Cadeia de caracteres de consulta estiver selecionada, insira outro valor: o nome do cabeçalho ou parâmetro da cadeia de caracteres de consulta. Um exemplo de uso é exibido. |
| Nome completo da versão da API | swagger-petstore-v1 | Nome exclusivo em sua instância de 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 determinados níveis de serviço) | Opcionalmente, um ou mais produtos aos quais a versão da API está associada. Para publicar a API, precisa de 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 agora aparece abaixo do Swagger Petstore na Lista de APIs. Agora você vê duas APIs: Original e v1.
Nota
Se você adicionar uma versão a uma API sem versão, um Original também será criado automaticamente. Esta versão responde no URL padrão. A criação de uma versão Original garante que os chamadores existentes não sejam quebrados pelo processo de adição de uma versão. Se você criar uma nova API com versões habilitadas no início, um Original não será criado.
Editar uma versão
Depois de adicionar a versão, agora você pode editá-la e configurá-la como uma API separada de uma Original. As alterações em uma versão não afetam outra. Por exemplo, adicione ou remova operações de API ou edite a especificação OpenAPI. Para obter mais informações, consulte Editar uma API.
Adicionar a versão a um produto
Para os autores de chamadas verem a nova versão, esta tem de ser adicionada a um produto. Se ainda não adicionou a versão a um produto, pode adicioná-la a um produto a qualquer momento.
Por exemplo, para adicionar a versão ao produto Unlimited :
- No portal do Azure, navegue até sua instância de Gerenciamento de API.
- Selecione Produtos>APIs ilimitadas>> + Adicionar.
- Selecione Swagger Petstore, 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 para uma única API lógica. Selecione o nome de uma API que tenha várias versões. O portal do Azure exibe seu conjunto de versões. Você pode personalizar o Nome e a Descrição de um conjunto virtual.
Você pode interagir diretamente com conjuntos de versões usando a CLI do Azure:
Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.
Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.
Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.
Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.
Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.
Para ver todos os seus 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 aparece 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 conjuntos de versões, consulte Versões no Gerenciamento de API do Azure.
Navegar até ao portal do programador para ver a versão
Se você já tentou o portal do desenvolvedor, você pode ver as versões da API lá.
- Selecione Portal do Programador no menu superior.
- Selecione APIs e, em seguida, selecione Swagger Petstore.
- Você verá uma lista suspensa com várias versões ao lado do nome da API.
- Selecione v1.
- Repare no URL do pedido da primeira operação na lista. Indica que o caminho do URL da API inclui v1.
Próximos passos
Neste tutorial, ficou a saber como:
- Adicionar uma nova versão a uma API existente
- Escolher um esquema de versão
- Adicionar a versão a um produto
- Navegar até ao portal do programador para ver a versão
Avance para o tutorial seguinte: