Criar uma configuração de API

Pré-requisitos

Antes de poder criar uma configuração da API, certifique-se de 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.

• Ter criado opcionalmente uma API, conforme descrito no artigo 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 abaixo 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 caráter de 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.

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 mais informações 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 seguinte comando 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.
   • PROJECT_ID especifica o Google Cloud ID do projeto.
   • 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 uma configuração está a ser criada, 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 --project=PROJECT_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 posteriormente, 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 \
  --project=PROJECT_ID --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 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)"

Configurações da API Listing

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

gcloud api-gateway api-configs list --project=PROJECT_ID

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

Use os IDs do projeto, da API e da configuração para obter informações detalhadas sobre a configuração da API:

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_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 de 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 de 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 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

Por 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

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