Compartilhar via

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"

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

Atualizar propriedades da API

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.

O exemplo a seguir atualiza o título da petstore-api API para Petstore API v2.

az apic api update --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --title "Petstore API v2"

O exemplo a seguir define a propriedade booleana interna personalizada da API como false.

az apic api update --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --set custom_properties.internal=false

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