Criar uma configuração de API

Esta página descreve como criar uma configuração da API para implementar no API Gateway.

Antes de começar

Antes de criar uma configuração de API, confirme que tem:

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

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

  Nota: se quiser usar o OpenAPI 3.x, certifique-se de que atualiza o Google Cloud CLI antes de começar a criar uma configuração da API para evitar erros ao carregar a definição da API.

• Criou opcionalmente uma API, conforme descrito em Criar uma API. Se a API ainda não existir, a criação da configuração da API cria-a.

Requisitos do ID de configuração da API

Muitos dos comandos gcloud apresentados neste tutorial requerem que especifique o ID da configuração da API no formato: CONFIG_ID. O API Gateway aplica os seguintes requisitos ao ID de configuração da API:

• Tem de ter um comprimento máximo de 63 carateres.
• Tem de conter apenas letras minúsculas, números ou travessões.
• Não pode começar com um traço.
• Não pode conter um sublinhado.

Criar uma configuração de API

Use a CLI Google Cloud para carregar a definição da API e criar uma configuração da API. Quando carrega a definição da API, tem de especificar o nome da API. Se a API ainda não existir no API Gateway, este comando também a cria.

Nota: o API Gateway suporta a criação de definições de API como especificações OpenAPI para todos os serviços de back-end disponíveis. O API Gateway também suporta a utilização de definições e configurações de serviços gRPC para serviços gRPC no Cloud Run.

Se o managedService na sua definição da API estiver definido como um serviço ESPv2 beta, certifique-se de que o campo host (OpenAPI 2.0) ou o campo 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. Altere o diretório 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 sua API, consulte a vista geral da OpenAPI e o guia de início rápido: implemente uma API no API Gateway.

   Para mais informações sobre como criar uma definição e uma configuração de serviço gRPC para a sua definição de API, consulte os artigos Configurar um serviço gRPC e Introdução ao API Gateway e ao Cloud Run para gRPC.

2. Valide o ID do projeto devolvido pelo comando seguinte para se certificar de que o serviço não é criado no projeto errado.

   gcloud config list project

   Se precisar de alterar o projeto predefinido, execute o seguinte comando e substitua PROJECT_ID pelo Google Cloud ID do projeto Google Cloud no qual quer criar o serviço:

   gcloud config set project PROJECT_ID

3. Veja a ajuda para o comando api-configs create:

   gcloud api-gateway api-configs create --help

4. Execute o seguinte comando para criar a configuração da 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

   where:

   • CONFIG_ID especifica o ID da nova configuração da API.
   • API_ID especifica o ID da API do API Gateway associada a esta configuração da API. Se a API ainda não existir, este comando cria-a.
   • 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 o artigo Configurar uma conta de serviço para ver mais detalhes.

   À medida que cria a API e a configuração da API, o API Gateway envia informações para o terminal. Esta operação pode demorar vários minutos a ser concluída, uma vez que a configuração da API é propagada para os sistemas a jusante. A criação de uma configuração de API complexa pode demorar até dez minutos a ser concluída com êxito. Enquanto estiver a criar uma configuração, não tente criar outra configuração para a mesma API. Só é possível criar uma configuração para qualquer API de cada vez.

5. Após a conclusão com êxito, pode usar o seguinte comando para ver detalhes sobre a nova configuração da API:

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

   Este comando devolve 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 através do nome do serviço gerido da API. Pode encontrar este valor na coluna Serviço gerido da sua API na página de destino das APIs:

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

   Só tem de executar este comando uma vez quando cria a API. Se modificar a API mais tarde, não tem de executar novamente o comando.

A CLI gcloud aceita muitas opções, incluindo as descritas na referência gcloud. Além disso, para o API Gateway, pode definir as seguintes opções quando cria uma configuração da API:

• --async: devolve o controlo ao terminal imediatamente, sem esperar que a operação seja concluída.
• --display-name=NAME: especifica o nome a apresentar da configuração da API, ou seja, o nome apresentado na IU. Não use espaços no nome. Em alternativa, use hífenes e sublinhados. O valor predefinido é CONFIG_ID.
• --labels=KEY1=VALUE1,KEY2=VALUE2,...: especifica as etiquetas associadas à configuração da API.

Por 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

Pode ver as etiquetas no resultado do comando describe apresentado ou no comando list incluindo a opção --format:

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

Configurações da API Listing

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

gcloud api-gateway api-configs list 

Este comando devolve 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 as configurações de API de uma API específica num projeto:

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

Use a API e os IDs de configuração para obter 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

Não pode modificar uma configuração da API existente, exceto para atualizar as respetivas etiquetas e nome a apresentar.

Nota: sempre que carrega uma definição de API, o API Gateway cria uma nova configuração da API.

Para atualizar uma definição da API:

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

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

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

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

Por 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

Eliminar uma configuração de API

Aviso: se implementou a configuração da API num gateway, a configuração da API pode não ser eliminada até que o gateway deixe de usar essa configuração da API.

Antes de eliminar uma configuração da API que esteja em utilização, tem de:

• Implemente uma configuração de API diferente no gateway.
• Elimine o gateway.

Consulte o artigo Implementar uma API num gateway para saber mais.

Use o seguinte comando gcloud para eliminar uma configuração da API existente:

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

O que se segue?

• Implementar uma API num gateway