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 seu 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 Google Cloud console, a API e a configuração da 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 de configuração da API, no formato: CONFIG_ID. O gateway de API 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 da API.

**Observação** :o gateway de API é compatível com a criação de definições de API como especificações da OpenAPI em 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 Beta do ESPv2, 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.

Se a definição da API configurar cotas, verifique se as métricas e os limites de cota permanecem consistentes em todas as configurações de API ativas antes de criar uma nova. O gateway de API os aplica a toda a API, e não a uma configuração de API individual. Portanto, qualquer métrica ou limite declarado por uma nova configuração de API substitui a definição de toda a API. Se você renomear ou remover uma métrica, os gateways que ainda atendem a uma configuração de API anterior vão retornar erros para os métodos com cota aplicada. Para mais informações, consulte As cotas se aplicam a toda a API.

Para criar uma configuração de API:

Google Cloud Console do

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

Google Cloud CLI

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 a 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 saber mais sobre como criar a especificação OpenAPI para a definição da API, 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 Introdução ao gateway de API e ao Cloud Run para gRPC.

2. Valide o ID do projeto retornado pelo comando a seguir para garantir que o serviço não seja criado no projeto errado.

   gcloud config list project

   Se você precisar mudar o projeto padrão, execute o comando a seguir e substitua PROJECT_ID pelo Google Cloud ID do projeto 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 do gateway de API associado a esta configuração de 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 está sendo criada, não tente criar outra para a mesma API. Somente uma configuração pode ser criada para qualquer API por vez.

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 mais tarde, não será necessário 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 UI. 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 Google Cloud projeto.

Google Cloud Console do

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

1. No Google Cloud console do, 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 será exibida na página.

Google Cloud CLI

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.

Google Cloud Console do

1. No Google Cloud console do, 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 editar Editar.
6. Edite Nome de exibição ou Rótulos.
7. Clique em Salvar.

Google Cloud CLI

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

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

Google Cloud Console do

1. No Google Cloud console do, 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.

Google Cloud CLI

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

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

A seguir

• Implantar uma API em um gateway