Usar a CLI do Azure para gerenciar o seu inventário de API

  • Artigo

Este artigo mostra como usar comandos az apic api na CLI do Azure para adicionar e configurar APIs no inventário do Centro de API. Use comandos na CLI do Azure para executar script de operações para gerenciar seu inventário de API e outros aspectos do centro de API.

Pré-requisitos

  • Um centro de API na sua assinatura do Azure. Se você ainda não criou um, consulte Início Rápido: criar seu centro de API.

  • Para a CLI do Azure:

    Observação

    Os comandos az apic exigem a extensão da CLI do Azure apic-extension. Se você não tiver usado comandos az apic, a extensão poderá ser instalada dinamicamente quando você executar seu primeiro comando az apic ou instalar a extensão manualmente. Saiba mais sobre as extensões da CLI do Azure.

    Confira as notas sobre a versão para ver as últimas alterações e atualizações no apic-extension.

Registrar a API, a versão da API e a definição

As etapas a seguir mostram como criar uma API e associar uma única versão da API e uma definição de API. Para obter informações sobre o modelo de dados no Centro de API do Azure, confira Principais conceitos.

Criar uma API

Use o comando az apic api create para criar uma API no centro de API.

O exemplo a seguir cria uma API chamada Petstore API no grupo de recursos myResourceGroup e no centro de API myAPICenter. A API é uma API REST.

az apic api create  --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --title "Petstore API" --type "rest"

Observação

Depois de criar uma API, você pode atualizar as propriedades da API usando o comando az apic api update.

Criar uma versão da API

Use o comando az apic api version create para criar uma versão para a sua API.

O exemplo a seguir cria uma versão de API chamada v1-0-0 para a API petstore-api que você criou na seção anterior. A versão é definida como a fase do ciclo de vida de teste.

az apic api version create --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --version-id v1-0-0 --title "v1-0-0" --lifecycle-stage "testing"

Criar definição de API e adicionar arquivo de especificação

Use os comandos az apic api definition para adicionar uma definição e um arquivo de especificação que acompanha uma versão da API.

Criar uma definição

O exemplo a seguir usa o comando az apic api definition create para criar uma definição chamada openapi para a versão da API petstore-api que você criou na seção anterior.

az apic api definition create --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --version-id v1-0-0 --definition-id openapi --title "OpenAPI"

Importar um arquivo de especificação

Importe um arquivo de especificação para a definição usando o comando az apic api definition import-specification.

O exemplo a seguir importa um arquivo de especificação OpenAPI de uma URL acessível publicamente para a definição de openapi que você criou na etapa anterior. As propriedades name e version do recurso de especificação são passados como JSON.

az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id petstore-api --version-id v1-0-0 \
    --definition-id openapi --format "link" \
    --value 'https://petstore3.swagger.io/api/v3/openapi.json' \
    --specification '{"name":"openapi","version":"3.0.2"}'

Dica

Você pode importar o arquivo de especificação embutido definindo o parâmetro --format como inline e passando o conteúdo do arquivo usando o parâmetro --value.

Exportar um arquivo de especificação

Para exportar uma especificação de API do centro de API para um arquivo local, use o comando az apic api definition export-specification.

O exemplo a seguir exporta o arquivo de especificação da definição openapi que você criou na seção anterior para um arquivo local chamado specificationFile.json.

az apic api definition export-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id petstore-api --version-id v1-0-0 \
    --definition-id openapi --file-name "/Path/to/specificationFile.json"

Registrar a API de um arquivo de especificação – etapa única

Você pode registrar uma API de um arquivo de especificação local em uma única etapa usando o comando az apic api register. Com esta opção, uma versão e definição de API padrão são criadas automaticamente para a API.

O exemplo a seguir registra uma API no centro de API myAPICenter de um arquivo de definição OpenAPI local chamado specificationFile.json.

az apic api register --resource-group myResourceGroup \
    --service-name myAPICenter --api-location "/Path/to/specificationFile.json"
  • O comando define as propriedades da API, como nome e tipo, de valores no arquivo de definição.
  • Por padrão, o comando define o Estágio de ciclo de vida da API como design.
  • Ele cria uma versão de API nomeada de acordo com a propriedade version na definição de API (ou 1-0-0 por padrão) e uma definição de API nomeada de acordo com o formato de especificação (por exemplo, openapi).

Depois de registrar uma API, você pode atualizar as propriedades da API usando os comandos az apic api update, az apic api version update e az apic api definition update.

Excluir recursos de API

Use o comando az apic api delete para excluir uma API e todos os seus recursos de versão e definição. Por exemplo:

az apic api delete \
    --resource-group myResoureGroup --service-name myAPICenter \
    --api-id petstore-api

Para excluir versões e definições de API individuais, use az apic api version delete e az apic api definition delete, respectivamente.

Conteúdo relacionado