Tutorial: Use revisões para fazer alterações ininterruptas na API com segurança

Artigo
08/05/2024

APLICA-SE A: Todas as camadas de gerenciamento de API

Quando sua API estiver pronta para uso e for usada por desenvolvedores, você eventualmente precisará fazer alterações nessa API e, ao mesmo tempo, não interromper os chamadores de sua API. É também útil dar a conhecer aos programadores as alterações que efetuou.

No Gerenciamento de API do Azure, use revisões para fazer alterações de API ininterruptas para que você possa modelar e testar as alterações com segurança. Quando estiver pronto, você poderá fazer uma revisão atual e substituir sua API atual.

Para obter informações detalhadas, consulte Versões e revisões.

Neste tutorial, irá aprender a:

Adicionar uma nova revisão
Fazer alterações ininterruptas na sua revisão
Tornar a revisão atual e adicionar uma entrada de registo de alterações
Navegar até ao portal do programador para ver as alterações e o registo de alterações
Acessar uma revisão da API

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 revisão

Entre no portal do Azure e vá para sua instância de Gerenciamento de API.
No menu à esquerda, em APIs, selecione APIs.
Selecione API de conferência de demonstração na lista de APIs (ou outra API à qual você deseja adicionar revisões).
Selecione a guia Revisões .
Selecione + Adicionar revisão.

Gorjeta

Você também pode selecionar Adicionar revisão no menu de contexto (...) da API.
Forneça uma descrição para a sua nova revisão, para ajudar a lembrar para que ela é usada.
Selecione Criar.
A sua nova revisão está agora criada.

Nota

A API original permanece em Revisão 1. Trata-se da revisão que os utilizadores continuam a chamar, até optar por tornar uma revisão diferente atual.

Fazer alterações ininterruptas na sua revisão

Selecione Demo Conference API na lista de APIs.
Selecione o separador Estrutura junto à parte superior do ecrã.
Tenha em atenção que o seletor de revisões (diretamente acima do separador de estrutura) mostra a Revisão 2 como atualmente selecionada.

Gorjeta

Utilize o seletor de revisões para alternar entre revisões em que quer trabalhar.
Selecione + Adicionar Operação.
Defina sua nova operação como POST e o Nome para exibição, Nome e URL da operação como teste.
Guarde a nova operação.
Agora você fez uma alteração na Revisão 2. Use o seletor de revisão na parte superior da página para voltar para a Revisão 1.
Observe que sua nova operação não aparece na Revisão 1.

Tornar a revisão atual e adicionar uma entrada de registo de alterações

Portal
CLI do Azure

Selecione o separador Revisões no menu junto à parte superior da página.
Abra o menu de contexto (...) para Revisão 2.
Selecione Tornar atual.
Marque a caixa de seleção Publicar no log de alterações públicas para esta API , se quiser postar anotações sobre essa alteração. Forneça uma descrição para sua alteração que os desenvolvedores possam ver, por exemplo: Revisões de teste. Adicionada nova operação de "teste".
Revisão 2 é agora atual.

Para começar a usar 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.

Use este procedimento para criar e atualizar uma versão.

Execute o comando az apim api list para ver seus IDs de API:
```
az apim api list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table
```
O ID da API a ser usado no próximo comando é o Name valor. A revisão da ApiRevision API está na coluna.

Para criar a versão, com uma nota de versão, execute o comando az apim api release create :

az apim api release create --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --api-revision 2 --service-name apim-hello-world \
    --notes 'Testing revisions. Added new "test" operation.'

A revisão que você lança torna-se a revisão atual.

Para ver suas versões, use o comando az apim api release list :
```
az apim api release list --resource-group apim-hello-word-resource-group \
    --api-id echo-api --service-name apim-hello-world --output table
```
As anotações especificadas aparecem no log de alterações. Você pode vê-los na saída do comando anterior.

Quando você cria uma versão, o --notes parâmetro é opcional. Você pode adicionar ou alterar as notas posteriormente usando o comando az apim api release update :

az apim api release update --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --release-id 00000000000000000000000000000000 \
    --service-name apim-hello-world --notes "Revised notes."

Use o valor na Name coluna para o ID da versão.

Você pode remover qualquer versão executando o comando az apim api release delete :

az apim api release delete --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

Navegar até ao portal do programador para ver as alterações e o registo de alterações

Se você já tentou o portal do desenvolvedor, você pode revisar as alterações da API e o log de alterações lá.

No portal do Azure, navegue até sua instância de Gerenciamento de API.
No menu à esquerda, em APIs, selecione APIs.
Selecione Portal do desenvolvedor no menu superior.
No portal do desenvolvedor, selecione APIs e, em seguida, selecione API de conferência de demonstração.
Tenha em atenção que a nova operação test está agora disponível.
Selecione Changelog perto do nome da API.
Observe que sua entrada de log de alterações aparece na lista.

Acessar uma revisão da API

Cada revisão da sua API pode ser acessada usando uma URL especialmente formada. Adicione ;rev={revisionNumber} no final do caminho da URL da API, mas antes da cadeia de caracteres de consulta, para acessar uma revisão específica dessa API. Por exemplo, você pode usar essa URL para acessar a revisão 2 da API de conferência de demonstração:

https://apim-hello-world.azure-api.net/conf;rev=2/speakers

Você pode encontrar os caminhos de URL para as revisões da sua API na guia Revisões no portal do Azure.

Captura de ecrã dos URLs de revisão no portal.

Gorjeta

Você pode acessar a revisão atual da API usando o caminho da API sem a ;rev cadeia de caracteres, além da URL completa que acrescenta ao caminho da ;rev={revisionNumber} API.

Resumo

Neste tutorial, ficou a saber como:

Adicionar uma nova revisão
Fazer alterações ininterruptas na sua revisão
Tornar a revisão atual e adicionar uma entrada de registo de alterações
Navegar até ao portal do programador para ver as alterações e o registo de alterações
Acessar uma revisão da API

Próximos passos

Avance para o tutorial seguinte:

Publicar várias versões da sua API

Partilhar via