Como criar uma configuração de API

Pré-requisitos

Antes de criar uma configuração de API, verifique 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;

• 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 abaixo exigem que você especifique o ID de 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.

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 alterar o projeto padrão, execute o seguinte comando e substitua PROJECT_ID pelo ID do projeto do 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.
   • PROJECT_ID especifica o ID do projeto do Google Cloud.
   • SERVICE_ACCOUNT_EMAIL especifica a conta de serviço usada para assinar tokens de 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 --project=PROJECT_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 posteriormente, não precisará executar o comando novamente.

A CLI do Google Cloud 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 \
  --project=PROJECT_ID --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 acima ou no comando list, incluindo a opção --format:

gcloud api-gateway api-configs list \
  --api=API_ID --project=PROJECT_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 --project=PROJECT_ID

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 --project=PROJECT_ID

Use o projeto, 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 --project=PROJECT_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 acima 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  --project=PROJECT_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