Versões na Gestão de API do Azure

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

As versões permitem-lhe apresentar grupos de APIs relacionadas aos seus programadores. Pode utilizar versões para lidar com alterações interruptivas na sua API em segurança. Os clientes podem optar por utilizar a sua nova versão da API quando estiverem prontos, enquanto os clientes existentes continuam a utilizar uma versão mais antiga. As versões são diferenciadas através de um identificador de versão (que é qualquer valor de cadeia que escolher) e um esquema de controlo de versões permite que os clientes identifiquem a versão de uma API que pretendem utilizar.

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

Com versões você pode:

• Publique várias versões da sua API ao mesmo tempo.
• Use um caminho, cadeia de caracteres de consulta ou cabeçalho para diferenciar entre versões.
• Use qualquer valor de cadeia de caracteres que você deseja para identificar sua versão, que pode ser um número, uma data ou um nome.
• Mostre suas versões de API agrupadas no portal do desenvolvedor.
• Pegue uma API existente (sem versão) e crie uma nova versão dela sem quebrar os clientes existentes.

Comece com as versões seguindo nosso 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 o 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 todas as solicitações de API.

Por exemplo, e https://apis.contoso.com/products/v2 poderia referir-se à mesma products API, https://apis.contoso.com/products/v1 mas a 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 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 da 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.

Controle de versão baseado em cadeia de caracteres de consulta

Quando o esquema de controle de versão da cadeia de caracteres de consulta é usado, o identificador de versão precisa ser incluído em um parâmetro de cadeia de caracteres de consulta para quaisquer 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 ao usar o controle de versão baseado em cadeia de caracteres de consulta é: https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

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

Nota

Os parâmetros de consulta não são permitidos servers na propriedade de uma especificação OpenAPI. Se você exportar uma especificação OpenAPI de uma versão da API, uma cadeia de caracteres de consulta não aparecerá na 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 sejam quebrados pelo processo de adição de uma versão. Se você criar uma nova 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 versionada 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, que é então 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 de 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ões é automaticamente excluído 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 Gerenciador de Recursos ou a API do Gerenciador de Recursos do Azure.

Nota

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 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 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 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.

Portal do programador

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.

Gorjeta

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