Compartilhar via

Revisões no Gerenciamento de API do Azure

  • Artigo

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

As revisões permitem que você faça alterações nas APIs de maneira segura e controlada. Quando desejar fazer alterações, crie uma revisão. Em seguida, você poderá editar e testar a API sem afetar os consumidores da API. Quando estiver pronto, você tornará a revisão atual. Ao mesmo tempo, opcionalmente, poste uma entrada no log de alterações para manter os consumidores da API atualizados sobre o que foi alterado. O log de alterações é publicado no portal do desenvolvedor.

Observação

O portal do desenvolvedor não está disponível na camada de consumo.

Com as revisões, você pode:

  • Fazer alterações com segurança em políticas e definições de API, sem afetar a API de produção.
  • Experimentar as alterações antes de publicá-las.
  • Documentar as alterações feitas, de modo que os desenvolvedores possam entender as novidades.
  • Revertê-las caso encontre problemas.

Comece a usar as revisões seguindo nosso passo a passo.

Como acessar revisões específicas

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 3 da API customers:

https://apis.contoso.com/customers;rev=3/leads?customerId=123

Por padrão, cada revisão tem as mesmas configurações de segurança da revisão atual. Você poderá alterar deliberadamente as políticas de uma revisão específica se desejar ter uma segurança diferente aplicada a cada revisão. Por exemplo, o ideal é adicionar uma política de filtragem de IP para impedir que chamadores externos acessem uma revisão que ainda está em desenvolvimento.

Observação

O ;rev={id} deve ser acrescentado à ID da API e não ao caminho do URI.

Revisão atual

Uma revisão individual pode ser definida como a revisão atual. Essa revisão será usada para todas as solicitações de API que não especificam um número de revisão explícito na URL. Você poderá reverter para uma revisão anterior definindo essa revisão como a atual.

Defina uma revisão como a atual usando o portal do Azure. Se você usar o PowerShell, use o cmdlet New-AzApiManagementApiRelease.

Descrições da revisão

Ao criar uma revisão, você pode definir uma descrição para suas finalidades de acompanhamento. As descrições não são exibidas para seus usuários da API.

Quando você define uma revisão como a atual, também pode especificar uma observação pública de log de alterações. O log de alterações está incluído no portal do desenvolvedor para que os usuários da API o vejam. Modifique a observação do log de alterações usando o cmdlet Update-AzApiManagementApiRelease do PowerShell.

Cuidado

Se você estiver editando uma revisão não atual de uma API, não poderá alterar as seguintes propriedades:

  • Nome
  • Tipo
  • Descrição
  • Assinatura necessária
  • Versão da API
  • Descrição da versão da API
  • Caminho
  • Protocolos

Essas propriedades só podem ser alteradas na revisão atual. Se suas edições alterarem qualquer uma das propriedades acima de uma revisão não atual, a mensagem de erro Can't change property for non-current revision será exibida.

Fazer uma revisão offline

Uma revisão pode ser deixada offline, o que a torna inacessível para os chamadores, mesmo que eles tentem acessar a revisão por meio da URL. Você pode marcar uma revisão como offline usando o portal do Azure.

Observação

Sugerimos fazer revisões offline quando elas não estão sendo usadas para teste.

Versões e revisões

Versões e revisões são recursos distintos. Cada versão pode ter várias revisões, assim como uma API sem controle de versão. Você pode usar revisões sem usar versões ou vice-versa. Normalmente, as versões são usadas para separar as versões de API com alterações interruptivas, enquanto as revisões podem ser usadas para alterações secundárias e não interruptivas em uma API.

Se você descobrir que a sua revisão tem alterações interruptivas ou se desejar transformá-la formalmente em uma versão beta/de teste, crie uma versão com base em uma revisão. Usando o portal do Azure, clique em 'Criar Versão com base na Revisão' no menu de contexto da revisão na guia Revisões.