Criar uma configuração de API

Nesta página, descrevemos como criar uma configuração de API para implantação no gateway de API.

Antes de começar

Antes de criar uma configuração de API, faça o seguinte:

• Prepare seu ambiente de desenvolvimento conforme descrito em Configurar o ambiente de desenvolvimento.

• Crie uma definição de API como uma especificação OpenAPI.

• Se você estiver usando a Google Cloud CLI, crie uma API (opcional). Se a API não existir, a criação da configuração da API a criará.

  Observação: ao usar o console Google Cloud , a API e a configuração de API são criadas ao implantar a API em um gateway.

Requisitos do ID de configuração da API

Muitos dos comandos da CLI gcloud mostrados exigem que você especifique o ID da configuração da API, no formato: CONFIG_ID. A API Gateway aplica os seguintes requisitos ao ID de configuração da API:

• Os valores têm comprimento máximo de 63 caracteres.
• Use somente letras minúsculas, números ou hifens
• Não pode começar com um traço.
• Não pode conter um sublinhado.

Criar uma configuração de API

Crie uma configuração de API fazendo upload da definição de API.

Observação: o gateway de API é compatível com a criação de definições de API como especificações OpenAPI para todos os serviços de back-end disponíveis. O gateway de API também permite o uso das definições e configurações do serviço gRPC para serviços gRPC no Cloud Run.

Se o managedService na definição da API estiver definido como um serviço do ESPv2 Beta, verifique se o campo host (OpenAPI 2.0) ou server.url (OpenAPI 3.x) está definido como uma extensão x-google-endpoint na configuração da API.

Para criar uma configuração de API:

Console do Google Cloud

Crie uma configuração de API ao implantar uma API em um gateway.

CLI do Google Cloud

Faça upload da definição da API para criar uma configuração de API. Ao fazer o upload da definição da API, é necessário especificar o nome dela. Se a API ainda não existir no gateway de API, esse comando também a criará.

Observação: se você quiser usar o OpenAPI 3.x, atualize os componentes da CLI gcloud antes de criar uma configuração de API para evitar erros ao fazer upload da definição da API.

1. Mude para o diretório que contém a definição da API.

   Para mais informações sobre como criar a especificação OpenAPI para sua definição, consulte a Visão geral da OpenAPI e o Guia de início rápido: proteger o tráfego para um serviço com a CLI gcloud.

   Para mais informações sobre como criar uma definição e uma configuração do serviço gRPC para a definição da API, consulte Configurar um serviço gRPC e Começar a usar o gateway de API e o Cloud Run para gRPC.

2. Valide o ID do projeto retornado do seguinte comando para garantir que o serviço não seja criado no projeto incorreto.

   gcloud config list project

   Se você precisar mudar o projeto padrão, execute o seguinte comando e substitua PROJECT_ID pelo ID do projeto Google Cloud em que você quer criar o serviço:

   gcloud config set project PROJECT_ID

3. Veja a ajuda do comando api-configs create:

   gcloud api-gateway api-configs create --help

4. Execute este comando para criar a configuração de API:

   gcloud api-gateway api-configs create CONFIG_ID \
         --api=API_ID --openapi-spec=API_DEFINITION \
         --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

   onde:

   • CONFIG_ID especifica o ID da nova configuração da API.
   • API_ID especifica o ID da API Gateway associado à configuração da API. Se a API ainda não existir, este comando a criará.
   • API_DEFINITION especifica o nome da especificação OpenAPI que contém a definição da API.
   • SERVICE_ACCOUNT_EMAIL especifica a conta de serviço usada para assinar tokens para back-ends com autenticação configurada. Consulte Configurar a conta de serviço usada para criar configurações de API para mais detalhes.

   Durante a criação da API e da configuração da API, o gateway de API gera informações para o terminal. Essa operação pode levar vários minutos para ser concluída conforme a configuração da API é propagada para os sistemas downstream. A criação de uma configuração de API complexa pode levar até dez minutos para ser concluída. Enquanto uma configuração estiver sendo criada, não tente criar outra configuração para a mesma API. Só é possível criar uma configuração por vez para qualquer API.

5. Após a conclusão, o comando a seguir pode ser usado para ver detalhes sobre a nova configuração da API:

   gcloud api-gateway api-configs describe CONFIG_ID \
         --api=API_ID

   Este comando mostra o seguinte:

   createTime: '2020-02-04T18:33:11.882707149Z'
   displayName: CONFIG_ID
   gatewayConfig:
         backendConfig:
           googleServiceAccount: [e-mail]
   labels: ''
   name: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
   serviceRollout:
         rolloutId: 2020-02-04r2
   state: ACTIVE
   updateTime: '2020-02-04T18:33:12.219323647Z'

6. Ative a API usando o nome de serviço gerenciado da API. Esse valor está na coluna "Serviço gerenciado" da API na página de destino das APIs:

   gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog

   Você só precisa executar esse comando uma vez ao criar a API. Se você modificar a API depois, não precisará executar o comando novamente.

A CLI gcloud usa muitas opções, incluindo as descritas na referência da CLI do Google Cloud. Além disso, para o gateway de API, é possível definir as seguintes opções ao criar uma configuração de API:

• --async: retorna o controle para o terminal imediatamente, sem aguardar a conclusão da operação.
• --display-name=NAME: especifica o nome de exibição da configuração da API, o que significa o nome mostrado na IU. Não use espaços no nome. Use hifens e sublinhados. O valor padrão é CONFIG_ID.
• --labels=KEY1=VALUE1,KEY2=VALUE2,...: especifica rótulos associados à configuração da API.

Exemplo:

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL \
  --async --display-name=MyConfig --labels=a=1,b=2

É possível ver os rótulos na saída do comando describe mostrado ou no comando list, incluindo a opção --format:

gcloud api-gateway api-configs list \
  --api=API_ID --format="table(name, labels)"

Listar configurações da API

Liste todos os gateways de API implantados no seu projeto Google Cloud .

Console do Google Cloud

Para listar configurações de uma API específica em um projeto:

1. No console do Google Cloud , acesse a página Gateway de API.

   Acessar o gateway de API

2. Clique na API necessária.
3. Clique na guia Configurações.

A lista de configurações de API disponíveis vai aparecer na página.

CLI do Google Cloud

Para listar configurações da API para um projeto específico:

gcloud api-gateway api-configs list 

Este comando mostra o seguinte:

NAME                                                                                                 DISPLAY_NAME             ROLLOUT_ID    STATE     CREATE_TIME
projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID  CONFIG_ID     2020-02-04r0  ACTIVE  2020-02-04T16:18:02.369859863Z

Para listar configurações de uma API específica em um projeto:

gcloud api-gateway api-configs list --api=API_ID 

Use os IDs da API e da configuração para receber informações detalhadas sobre a configuração da API:

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID 

Atualizar uma configuração de API

Você não pode modificar uma configuração de API existente além de atualizar os rótulos e o nome de exibição.

Observação: sempre que você faz upload de uma definição de API, o gateway de API cria uma nova configuração de API.

Para atualizar uma definição de API:

1. Atualize a especificação OpenAPI que contém a definição da API.
2. Faça upload da definição da API para criar uma nova configuração de API.

Use o mesmo comando para criar a nova configuração de API que foi usada para criar a configuração inicial da API, conforme mostrado em Criar uma configuração de API.

Console do Google Cloud

1. No console do Google Cloud , acesse a página Gateway de API.

   Acessar o gateway de API

2. Clique na API necessária.
3. Clique na guia Configurações.
4. Clique na configuração de API necessária.
5. Clique em edit Editar.
6. Edite o Nome de exibição ou os Marcadores.
7. Clique em Salvar.

CLI do Google Cloud

Use o seguinte comando `gcloud` para atualizar uma configuração de API atual:

• --display-name
• --update-labels
• --clear-labels
• --remove-labels

Exemplo:

gcloud api-gateway api-configs update CONFIG_ID \
  --api=API_ID \
  --update-labels=a=1,b=2

Use o seguinte comando para ver todas as opções de atualização:

gcloud api-gateway api-configs update --help

Excluir uma configuração de API

Aviso : se você tiver implantado a configuração da API em um gateway, talvez ela não seja excluída até que o gateway não esteja mais usando a configuração dessa API.

Antes de excluir uma configuração de API que esteja em uso, você precisa:

• Implantar uma configuração de API diferente no gateway
• Exclua o gateway.

Para mais informações, consulte Implantar uma API em um gateway.

Console do Google Cloud

1. No console do Google Cloud , acesse a página Gateway de API.

   Acessar o gateway de API

2. Clique na API necessária.
3. Clique na guia Configurações.
4. Clique em Mais e em Excluir para excluir a configuração de API escolhida.

CLI do Google Cloud

Use o seguinte comando da CLI gcloud para excluir uma configuração de API atual:

gcloud api-gateway api-configs delete CONFIG_ID --api=API_ID --project=PROJECT_ID

A seguir

• Implantar uma API em um gateway