Partilhar via

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

  • Artigo

Este artigo mostra como usar az apic api comandos na CLI do Azure para adicionar e configurar APIs em seu inventário do centro de APIs. Use comandos na CLI do Azure para criar scripts de operações para gerenciar seu inventário de API e outros aspetos do seu centro de APIs.

Pré-requisitos

  • Um centro de API na sua subscrição do Azure. Se você ainda não criou um, consulte Guia de início rápido: criar sua central de API.

  • Para a CLI do Azure:

    • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

    • Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

      • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

      • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

      • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

    Nota

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

    Consulte as notas de versão para obter as alterações e atualizações mais recentes no apic-extension.

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

As etapas a seguir mostram como criar uma API e associar uma única versão e definição de API de API. Para obter informações básicas sobre o modelo de dados na Central de API do Azure, consulte Principais conceitos.

Criar uma API

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

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

O exemplo a seguir cria uma versão da API chamada v1-0-0 para a API petstore-api que você criou na seção anterior. A versão é definida para o estágio do ciclo de vida do 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 para 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 openapi que você criou na etapa anterior. As name propriedades e version do recurso de especificação são passadas 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"}'

Gorjeta

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

Exportar um arquivo de especificação

Para exportar uma especificação de API do seu 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 API a partir 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 essa opção, uma versão e uma 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 a partir 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, a partir de valores no arquivo de definição.
  • Por padrão, o comando define o estágio do ciclo de vida da API como design.
  • Ele cria uma versão de API nomeada de acordo com a version propriedade 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 API petstore-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 personalizada interna booleana 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 da 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 individuais da API, use az apic api version delete e az apic api definition delete, respectivamente.

Conteúdos relacionados