Versões no Gerenciamento de API do Azure

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

As versões permitem que você apresente 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 de cadeia de caracteres que você escolher) e um esquema de controle de versão permite que os clientes identifiquem qual versão de uma API deseja usar. Este artigo descreve como usar versões no Gerenciamento de API.

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 versões, você pode:

• Publique várias versões da API ao mesmo tempo.
• Use um caminho, uma cadeia de caracteres de consulta ou um cabeçalho para diferenciar entre as versões.
• Use qualquer cadeia de caracteres para identificar sua versão. Pode ser um número, uma data ou um nome.
• Mostrar as versões da API agrupadas no portal do desenvolvedor.
• Crie uma nova versão de uma API existente (não com versão) sem afetar os clientes existentes.

Comece a usar as versões completando um passo a passo.

Esquemas de controle de versão

Diferentes desenvolvedores de API têm requisitos diferentes para controle de versão. O Gerenciamento de API do Azure não prescreve uma única abordagem para controle de versão, mas fornece várias opções.

Controle de versão baseado em caminho

Quando o esquema de controle de versão de 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 poderia se referir à mesma products API, mas a versões v1 e v2.

O formato de uma URL de solicitação da API quando você usa versionamento baseado em caminho é https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Controle de versão baseado em cabeçalho

Quando o esquema de controle de versão de 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, você pode 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 controle de versão da cadeia de consulta é usado, o identificador de versão precisa ser incluído em um parâmetro de cadeia de caracteres de consulta para solicitações de API. Você pode especificar o nome do parâmetro de cadeia de caracteres de consulta.

O formato de uma URL de solicitação de API quando você usa o controle de versão baseado 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 poderia se referir à mesma products API, mas a versões v1 e v2.

Versões originais

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

Como as versões são representadas

O Gerenciamento de API 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 controle de versão usado para direcionar solicitações para versões especificadas.

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

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

Um conjunto de versão é 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.

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 em seus recursos de Gerenciamento de API:

• Um novo conjunto de versões é criado.
• A versão existente é mantida e configurada como a versão da Original API. A API está vinculada ao conjunto de versões, mas um identificador de versão não precisa ser especificado.
• A nova versão é criada como uma nova API e está vinculada ao conjunto de versões. Um esquema de controle de versão e um identificador devem ser usados para acessar a nova API.

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 versionamento. 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 que têm alterações interruptivas, e as revisões podem ser usadas para alterações secundárias e não interruptivas em uma API.

Se você descobrir que sua revisão tem alterações significativas ou se quiser transformar formalmente sua revisão em uma versão beta/teste, você poderá criar uma versão a partir de uma revisão. No portal do Azure, selecione Criar Versão nesta Revisão no menu de contexto de revisão (...) na guia Revisões .

Portal do desenvolvedor

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

Nos detalhes de uma API, você também pode ver uma lista de todas as versões da API. Uma Original versão é exibida sem um identificador de versão: