Versões no Gerenciamento de API do Azure

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

As versões permitem apresentar grupos de APIs relacionadas aos desenvolvedores. Você pode usar versões para lidar com alterações significativas em sua API com segurança. Os clientes podem optar por usar sua nova versão de API quando estão prontos, enquanto os clientes existentes continuam a usar uma versão mais antiga. As versões são diferenciadas por meio de um identificador de versão (que é qualquer valor da cadeia de caracteres escolhido) e um esquema de versão permite que os clientes identifiquem qual versão de uma API eles querem usar.

Para a maioria das finalidades, cada versão da API pode ser considerada sua própria API independente. Duas versões de API diferentes podem ter diferentes conjuntos de operações e políticas.

Com as versões, você pode:

• publicar diversas versões da API ao mesmo tempo.
• usar um caminho, uma cadeia de caracteres de consulta ou um cabeçalho para diferenciar entre as versões.
• usar qualquer valor de cadeia de caracteres desejado para identificar sua versão, que pode ser um número, uma data ou um nome.
• mostrar suas versões de API agrupadas no portal do desenvolvedor.
• pegar uma API existente (sem versão) e criar uma nova versão dela sem interromper os clientes existentes.

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

Esquemas de controle de versão

Diferentes desenvolvedores de API têm requisitos diferentes para o uso da versão. O Gerenciamento de API do Azure não aconselha uma abordagem para o uso da versão, pelo contrário, ele dá várias opções.

Versão baseada em caminhos

Quando o esquema de versão do caminho é usado, o identificador de versão precisa ser incluído no caminho da URL para quaisquer solicitações de API.

Por exemplo, https://apis.contoso.com/products/v1 e https://apis.contoso.com/products/v2 podem se referir à mesma products API, mas às versões v1 e v2, respectivamente.

O formato de uma URL de solicitação de API ao usar o controle de versão baseado em caminhos é: https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Versão baseada em cabeçalhos

Quando o esquema de versão do cabeçalho é usado, o identificador de versão precisa ser incluído em um cabeçalho de solicitação HTTP para quaisquer solicitações de API. Você pode especificar o nome do cabeçalho de solicitação HTTP.

Por exemplo, é possível criar um cabeçalho personalizado chamado Api-Version e os clientes podem especificar v1 ou v2 no valor desse cabeçalho.

Versão baseada em cadeia de caracteres de consulta

Quando o esquema de versão baseada em cadeia de caracteres de consulta é usado, o identificador de versão precisa ser incluído em um parâmetro da cadeia de caracteres de consulta para quaisquer solicitações de API. Você pode especificar o nome do parâmetro da cadeia de caracteres de consulta.

O formato de uma URL de solicitação de API ao usar a versão baseada em cadeia de caracteres de consulta é: https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

Por exemplo, https://apis.contoso.com/products?api-version=v1 e https://apis.contoso.com/products?api-version=v2 podem se referir à mesma products API, mas às versões v1 e v2, respectivamente.

Observação

Os parâmetros de consulta não são permitidos na servers propriedade de uma especificação do OpenAPI. Se você exportar uma especificação do OpenAPI a partir de uma versão da API, uma cadeia de caracteres de consulta não aparecerá no URL do servidor.

Versões originais

Se você adicionar uma versão a uma API sem versão, uma Original versão será criada automaticamente e responderá na URL padrão sem um identificador de versão especificado. A Original versão garante que os chamadores existentes não serão interrompidos pelo processo de adição de uma versão. Se você criar uma API com versões habilitadas no início, uma Original versão não será criada.

Como as versões são representadas

O Gerenciamento de API do Azure mantém um recurso chamado conjunto de versões, que representa um conjunto de versões para uma única API lógica. Um conjunto de versões contém o nome de exibição da API com versão e o esquema de versão usado para direcionar solicitações para as versões especificadas.

Cada versão de uma API é mantida como seu próprio recurso de API, associado a um conjunto de versões. Um conjunto de versões pode conter APIs com operações ou políticas diferentes. Você pode fazer alterações significativas entre as versões em um conjunto.

O portal do Azure cria conjuntos de versão para você. É possível modificar o nome e a descrição de um conjunto de versões no portal do Azure.

Um conjunto de versões é excluído automaticamente quando a versão final é excluída.

Você pode exibir e gerenciar conjuntos de versões diretamente usando a CLI do Azure, o Azure PowerShell, os modelos do Resource Manager ou a API do Azure Resource Manager.

Observação

Todas as versões em um conjunto de versões têm o mesmo esquema de controle de versão, com base no esquema de controle de versão usado quando você adiciona uma versão a uma API pela primeira vez.

Migrando uma API sem versão para uma API com versão

Quando você usa o portal do Azure para habilitar o controle de versão em uma API existente, as seguintes alterações são feitas nos recursos de Gerenciamento de API:

• Um novo conjunto de versões é criado.
• A versão existente é mantida e configurada como a Original versão da API. A API está vinculada ao conjunto de versões, mas não requer que um identificador de versão seja especificado.
• A nova versão é criada como uma nova API e está vinculada ao conjunto de versões. Essa nova API deve ser acessada usando o esquema de controle de versão e o identificador.

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.

Portal do desenvolvedor

O portal do desenvolvedor lista cada versão de uma API separadamente.

Os detalhes de uma API também mostram uma lista de todas as versões dessa API. Uma Original versão é exibida sem um identificador de versão.

Dica

As versões da API precisam ser adicionadas a um produto antes que sejam visíveis no portal do desenvolvedor.