Como 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, confirme se você tem:

• Prepare seu ambiente de desenvolvimento conforme descrito em Como configurar seu ambiente de desenvolvimento.

• criou uma definição de API como uma especificação OpenAPI;

  Observação: se você quiser usar a OpenAPI 3.x, atualize o Google Cloud CLI antes de começar a criar uma configuração de API para evitar erros ao fazer upload da definição de API.

• Se preferir, crie uma API, conforme descrito em Como criar uma API. Se a API ainda não existe, a criação dela é criada.

Requisitos do ID de configuração da API

Muitos dos comandos gcloud mostrados neste tutorial 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.

Como criar uma configuração de API

Use a Google Cloud CLI para fazer upload da definição da API e 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: 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. A API Gateway 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:

1. Mude o diretório 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: implantar uma API no gateway de API.

   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 Como configurar um serviço gRPC e Primeiros passos com o gateway de API e o Cloud Run para gRPC.

2. Valide o código 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. Para mais informações, consulte Como configurar uma conta de serviço.

   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. Somente uma configuração pode ser criada 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 Google Cloud CLI usa muitas opções, incluindo as descritas na referência do gcloud. 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)"

Como listar configurações da API

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 a API e os IDs de configuração para ver informações detalhadas sobre a configuração:

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

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

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

Como 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 Como implantar uma API em um gateway.

Use o seguinte comando 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

• Como implantar uma API em um gateway