Tutorial: Usar revisões para fazer alterações sem interrupções na API com segurança

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

Quando sua API estiver pronta e for usada por desenvolvedores, e algum momento será necessário fazer alterações nessa API e, ao mesmo tempo, não interromper os chamadores de sua API. Também é útil permitir que os desenvolvedores saibam sobre as alterações feitas por você.

No Gerenciamento de API do Azure, use revisões para fazer alterações sem interrupção na API a fim de modelar e testar as alterações com segurança. Quando estiver pronto, você pode tornar uma revisão vigente e substituir a API atual.

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

Neste tutorial, você aprenderá a:

• Adicionar uma nova revisão
• Fazer alterações sem interrupção em sua revisão
• Torne sua revisão a atual e adicione uma entrada ao log de alterações
• Procurar no portal do desenvolvedor para ver as alterações e o log de alterações
• Acessar uma revisão de API

Pré-requisitos

• Conheça a terminologia do Gerenciamento de API do Azure.
• Conclua o seguinte guia de início rápido: Criar uma instância do Gerenciamento de API do Azure.
• Além disso, conclua o seguinte tutorial: Importar e publicar sua primeira API.

Adicionar uma nova revisão

1. Entre no portal do Azure e vá até a sua instância do Gerenciamento de API.

2. No menu do lado esquerdo, em APIs, selecione APIs.

3. Selecione Demonstração da API de Conferência na lista de APIs (ou outra API à qual você deseja adicionar revisões).

4. Selecione a guia Revisões.

5. Selecione + Adicionar revisão.

   

   Dica

   Também é possível selecionar Adicionar revisão no menu de contexto ( ... ) da API.

6. Forneça uma descrição para a nova revisão, para ajudar você a se lembrar da função dela.

7. Selecione Criar.

8. Sua nova revisão foi criada.

   Observação

   Sua API original permanece na Revisão 1. Essa é a revisão que seus usuários continuarão a chamar até que você opte por tornar uma revisão diferente a atual.

Fazer alterações sem interrupção em sua revisão

1. Selecione Demonstração de API de Conferência na lista de APIs.

2. Selecione a guia Design na parte superior da tela.

3. Observe que o seletor de revisão (diretamente acima da guia de design) mostra a revisão atual como Revisão 2.

   Dica

   Use o seletor de revisão para alternar entre as revisões nas quais você deseja trabalhar.

4. Selecione + Adicionar Operação.

5. Defina a nova operação como POST e o Nome de exibição, Nome e URL da operação como teste.

6. Salve sua nova operação.

   

7. Agora você fez uma alteração em Revisão 2. Use o seletor de revisão na parte superior da página para alternar novamente para Revisão 1.

8. Observe que a nova operação não aparece em Revisão 1.

Torne sua revisão a atual e adicione uma entrada ao log de alterações

Portal

1. Selecione a guia Revisões no menu próximo à parte superior da página.

2. Abra o menu de contexto (...) para a Revisão 2.

3. Selecione Tornar atual.

4. Marque Postar no log de alterações públicas para esta API se quiser postar observações sobre essa alteração. Forneça uma descrição para a alteração que os desenvolvedores possam ver, por exemplo: Teste de revisões. Adicionada uma nova operação de "teste".

5. Agora, a Revisão 2 é a atual.

   

CLI do Azure

Para começar a usar a CLI do Azure:

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no 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 obter mais informações, 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 ver outras opções de entrada, confira Conectar-se com 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 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 versão mais recente, execute az upgrade.

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

1. Execute o comando az apim api list para ver as IDs da API:

   az apim api list --resource-group apim-hello-word-resource-group \
       --service-name apim-hello-world --output table
   

   A ID da API a ser usada no próximo comando é o valor Name. A revisão da API está na coluna ApiRevision.

2. Para criar a versão, com uma nota sobre a 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 liberada se torna a revisão atual.

3. Para ver as 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 notas especificadas são exibidas no log de mudanças. Você poderá vê-las na saída do comando anterior.

4. Quando você cria uma versão, o parâmetro --notes é 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 da coluna Name para a ID da versão.

Remova 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

Procurar no portal do desenvolvedor para ver as alterações e o log de alterações

Se você tiver tentado o portal do desenvolvedor, poderá revisar as alterações da API e o log de alterações lá.

1. No portal do Azure, navegue até a instância do Gerenciamento de API.
2. No menu do lado esquerdo, em APIs, selecione APIs.
3. Selecione Portal do desenvolvedor no menu superior.
4. No portal do desenvolvedor, selecione APIs e, depois, selecione Demonstração da API de Conferência.
5. Observe que sua nova operação de teste já está disponível.
6. Clique em Log de alterações ao lado do nome da API.
7. Observe que a entrada no log de alterações aparece na lista.

Acessar uma revisão de API

Cada revisão na API pode ser acessada usando uma URL especialmente formada. Acrescente ;rev={revisionNumber} ao final da URL da API, mas antes da cadeia 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 API na guia Revisões no portal do Azure.

Dica

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

Resumo

Neste tutorial, você aprendeu a:

• Adicionar uma nova revisão
• Fazer alterações sem interrupção em sua revisão
• Torne sua revisão a atual e adicione uma entrada ao log de alterações
• Procurar no portal do desenvolvedor para ver as alterações e o log de alterações
• Acessar uma revisão de API

Próximas etapas

Prosseguir para o próximo tutorial:

Publicar várias versões da sua API