Compartilhar via

Revisões no Gerenciamento de API do Azure

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

As revisões permitem que você faça alterações em suas APIs de maneira controlada e segura. Quando você quiser fazer alterações, crie uma nova revisão. Em seguida, você pode editar e testar sua API sem incomodar os consumidores de API. Quando estiver pronto, você atualiza sua revisão. Ao mesmo tempo, opcionalmente, você pode postar uma entrada no log de alterações para manter seus consumidores de API atualizados com as alterações feitas. O log de alterações é publicado no portal do desenvolvedor.

Observação

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

Com revisões, você pode:

  • Faça alterações com segurança em suas definições e políticas de API, sem incomodar sua API de produção.
  • Experimente as alterações antes de publicá-las.
  • Documente as alterações feitas, para que os desenvolvedores possam entender as novidades.
  • Revertê-las caso encontre problemas.

Inicie revisões seguindo nosso guia passo a passo.

Acessando revisões específicas

Cada revisão para sua API pode ser acessada usando uma URL especialmente formada. Acrescente ;rev={revisionNumber} ao 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 revisão 3 da customers 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 que a 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.

Observação

O ;rev={id} deve ser adicionado 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 é 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 de revisão

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

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

Cuidado

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

  • Nome
  • Tipo
  • Description
  • 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 dessas propriedades em uma revisão não atual, a mensagem Can't change property for non-current revision de erro será exibida.

Realizar uma revisão offline

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

Observação

Sugerimos colocar as revisões offline quando você não as estiver usando para teste.

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 não versionada. Você pode usar revisões sem usar versões ou vice-versa. Normalmente, as versões são usadas para separar versões de API com mudanças disruptivas, enquanto as revisões podem ser usadas para alterações menores e não disruptivas em uma API.

Se a revisão tiver alterações significativas ou se você quiser transformar formalmente sua revisão em uma versão beta/teste, você poderá criar uma versão a partir de uma revisão. Usando o portal do Azure, selecione "Criar Versão da Revisão" no menu de contexto de revisão na guia Revisões.

  • Last updated on