Revisões na Gestão de API do Azure

  • Artigo

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

As revisões permitem-lhe fazer alterações às suas APIs de forma controlada e segura. Quando quiser fazer alterações, crie uma nova revisão. Em seguida, pode editar e testar a API sem perturbar os seus consumidores da API. Quando estiver pronto, torne a revisão atual. Ao mesmo tempo, pode publicar opcionalmente uma entrada no registo de alterações, para manter os seus consumidores da API atualizados com o que se alterou. O registo de alterações é publicado no seu portal do programador.

Nota

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

Com as revisões, você pode:

  • Faça alterações com segurança nas definições e políticas da API, sem perturbar a API de produção.
  • Experimente as alterações antes de publicá-las.
  • Documente as alterações feitas para que seus desenvolvedores possam entender o que há de novo.
  • Reverta se encontrar problemas.

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

Acesso a revisões específicas

Cada revisão da sua API pode ser acessada usando uma URL especialmente formada. Anexe ;rev={revisionNumber} no final 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 customers revisão 3 da API:

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ê pode alterar deliberadamente as políticas para uma revisão específica se quiser ter segurança diferente aplicada para cada revisão. Por exemplo, talvez você queira adicionar uma política de filtragem de IP para impedir que chamadores externos acessem uma revisão que ainda está em desenvolvimento.

Nota

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

Revisão atual

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

Você pode definir uma revisão como atual usando o portal do Azure. Se você usar o PowerShell, poderá usar o New-AzApiManagementApiRelease cmdlet.

Descrições das revisões

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

Ao definir uma revisão como atual, você também pode, opcionalmente, especificar uma nota pública de log de alterações. O log de alterações é incluído no portal do desenvolvedor para que os usuários da API visualizem. Você pode modificar sua nota de log de alterações usando o Update-AzApiManagementApiRelease cmdlet PowerShell.

Atenção

Se estiver a editar uma revisão não atual de uma API, não poderá alterar as seguintes propriedades:

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

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

Colocar uma revisão offline

Uma revisão pode ser colocada offline, o que a torna inacessível para os chamadores, mesmo que tentem aceder à revisão através do seu URL. Você pode marcar uma revisão como offline usando o portal do Azure.

Nota

Sugerimos que as revisões sejam feitas off-line quando você não as estiver usando para testes.

Versões e revisões

Versões e revisões são características distintas. Cada versão pode ter várias revisões, assim como uma API sem versão. Você pode usar revisões sem usar versões, ou o contrário. Normalmente, as versões são usadas para separar versões de API com alterações de quebra, enquanto as revisões podem ser usadas para alterações menores e ininterruptas em uma API.

Se você achar que sua revisão tem alterações de quebra, ou se você deseja transformar formalmente sua revisão em uma versão beta/teste, você pode criar uma versão a partir de uma revisão. Usando o portal do Azure, clique em 'Criar versão da revisão' no menu de contexto de revisão na guia Revisões.