Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
APLICA-SE A: Todas as camadas de gerenciamento de API
Há situações em que é impraticável para todos os consumidores de API usar 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 detalhadas, consulte Versões e revisões.
Gorjeta
As equipes de API podem usar esse recurso em espaços de trabalho. Os espaços de trabalho fornecem acesso administrativo isolado às APIs e possuem os seus próprios ambientes de execução de API.
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
- Exibir a versão no portal do desenvolvedor
Pré-requisitos
- Saiba a terminologia da Gestão de API do Azure.
- Conclua o início rápido Criar uma instância de Gerenciamento de API do Azure.
- Conclua o tutorial Importar e publicar sua primeira API.
Adicionar uma nova versão
- No portal do Azure, navegue até sua instância de Gerenciamento de API.
- No menu à esquerda, na seção APIs, selecione APIs.
- Localizar 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.
Gorjeta
Você também pode habilitar versões ao criar uma nova API. Na tela Adicionar API, selecione Versão desta API?.
Escolher um esquema de versões
No Gerenciamento de API, escolhe como os chamadores especificam a versão da API, selecionando um esquema de controle de versão : Caminho, Cabeçalho, ou Cadeia de consulta. No exemplo a seguir, Path é usado como o esquema de controle de versão.
Na janela Criar uma nova API como uma versão, insira os valores da tabela a seguir. Em seguida, selecione Criar para criar sua versão.
| Configuração | valor | Descrição |
|---|---|---|
| Identificador de versão | v1 | Indicador associado ao 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 selecionar cabeçalho ou cadeia de caracteres de consulta, insira outro valor: o nome do parâmetro de cabeçalho ou da cadeia de caracteres de consulta. Um exemplo de uso é exibido. |
| Nome completo da versão da API | swagger-petstore-openapi-3-0-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, esse valor é o nome da nova API. |
| Produtos | Ilimitado (fornecido em alguns 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 aparece em Swagger Petstore - OpenAPI 3.0 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, uma versão original também será criada automaticamente. Esta versão responde no URL padrão. A versão original garante que as chamadas de chamadores existentes ainda funcionem depois que a versão for adicionada. 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, 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 obter mais informações, consulte Editar uma API.
Adicionar a versão a um produto
Para que os utilizadores vejam a nova versão, esta deve ser adicionada a um produto. Se ainda não adicionou a versão a um produto, pode fazê-lo a qualquer momento.
Para adicionar a versão a um produto:
- No portal do Azure, navegue até sua instância de Gerenciamento de API.
- Em APIs no painel esquerdo, selecione Produtos.
- Selecione o produto e, em seguida, selecione APIs no painel esquerdo.
- Selecione + Adicionar.
- Selecione a API.
- Clique em Selecionar.
Utilizar 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. 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.
Você pode interagir diretamente com conjuntos de versões usando a CLI do Azure:
Use o ambiente Bash no Azure Cloud Shell. Para mais informações, veja Get started with 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 Autenticar no Azure usando a CLI do Azure.
Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre extensões, consulte Usar e gerenciar extensões com a 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 <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 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 <resource-group-name> \
--service-name <API-Management-service-name> --version-set-id <ID from the Name column>
Para obter mais informações sobre conjuntos de versões, consulte 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á.
- Selecione do portal do desenvolvedor na parte superior da janela.
- Selecione APIs e, em seguida, selecione Swagger Petstore.
- Você verá um menu suspenso com várias versões listadas ao lado do nome da API.
- Selecione v1.
- Observe o URL do pedido da primeira operação da lista. Indica que o caminho do URL da API inclui v1.
Próximo passo
Vá para o próximo tutorial: