Como implantar uma API em um gateway

Pré-requisitos

Antes de implantar uma configuração de API no gateway de API, verifique se você:

Requisitos de ID do gateway

Muitos dos comandos gcloud mostrados abaixo exigem que você especifique o ID do gateway, no formato: GATEWAY_ID. A API Gateway aplica os seguintes requisitos aos IDs do gateway:

  • Precisa ter no máximo 49 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 definir o endpoint da configuração da API implantada

Quando você implanta uma configuração de API em um gateway, o gateway de API cria um URL exclusivo para o gateway no domínio gateway.dev. Seus clientes de API usam um URL no formulário abaixo para acessar a configuração de API implantada:

https://GATEWAY_ID-HASH.REGION_CODE.gateway.dev

em que GATEWAY_ID é o nome do gateway, HASH é o código hash exclusivo gerado quando você implantou a API, e REGION_CODE é o código para a região do GCP onde você implantou o gateway.

Exemplo:

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

Implantar uma configuração de API em um gateway

Use a Google Cloud CLI para implantar uma configuração de API em um gateway. Ao implantar a configuração da API, é necessário especificar o nome dela. Se o gateway ainda não existir para a API, este comando também o criará.

Para implantar uma configuração de API em um gateway, siga estas etapas:

  1. 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
  2. Veja a ajuda do comando gateway create:

    gcloud api-gateway gateways create --help
  3. Execute o seguinte comando para implantar a configuração da API no gateway:

    gcloud api-gateway gateways create GATEWAY_ID \
      --api=API_ID --api-config=CONFIG_ID \
      --location=GCP_REGION --project=PROJECT_ID

    onde:

    • GATEWAY_ID especifica o ID do novo gateway; Se o gateway ainda não existir, este comando o criará.
    • API_ID especifica o ID da API Gateway da API associado a este gateway;
    • CONFIG_ID especifica o ID da configuração da API implantada no gateway; Especifique uma configuração de API ao criar um gateway.
    • GCP_REGION especifica a região do GCP para o gateway implantado;

    • PROJECT_ID especifica o ID do projeto do Google Cloud.

    Durante a criação do gateway, o gcloud gera informações para o terminal.

  4. Após a conclusão, o comando a seguir pode exibir detalhes sobre o gateway:

    gcloud api-gateway gateways describe GATEWAY_ID \
      --location=GCP_REGION --project=PROJECT_ID

    Este comando mostra o seguinte:

    apiConfig: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
    createTime: '2020-02-05T13:44:12.997862831Z'
    defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
    displayName: GATEWAY_ID
    name: projects/PROJECT_ID/locations/GCP_REGION/gateways/GATEWAY_ID
    serviceAccount:
      email: gateway-111111@222222-tp.iam.gserviceaccount.com
    state: ACTIVE
    updateTime: '2020-02-05T13:45:00.844705087Z'

    Observe o valor da propriedade defaultHostname. Esta é a parte do nome do host do URL do gateway. Para acessar uma configuração de API implantada nesse gateway, use um URL no formulário:

    https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

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 um gateway:

  • --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 do gateway, o que significa o nome mostrado na IU. Não use espaços no nome. Use hifens e sublinhados. O valor padrão é GATEWAY_ID.
  • --labels=KEY1=VALUE1,KEY2=VALUE2,...: especifica os rótulos associados ao gateway.

Como listar gateways

Para listar gateways para um projeto específico:

gcloud api-gateway gateways list --project=PROJECT_ID

Esse comando retorna a saída no formato:

GATEWAY_ID        LOCATION       DISPLAY_NAME     STATE     CREATE_TIME          UPDATE_TIME
my-gateway        us-central1    my-gateway       ACTIVE    2021-01-07T00:04:19  2022-05-21T00:33:46

Para listar gateways para um projeto e uma região específicos:

gcloud api-gateway gateways list --location=GCP_REGION --project=PROJECT_ID

Use uma expressão filter para listar os gateways associados a uma API específica:

gcloud api-gateway gateways list \
  --filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_ID/*" \
  --project=PROJECT_ID

Ou use este filter para listar gateways para uma configuração de API específica:

gcloud api-gateway gateways list \
  --filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID" \
  --project=PROJECT_ID

Use o ID do projeto, da região e do gateway para ver informações detalhadas sobre o gateway, incluindo a identidade da configuração da API implantada no gateway:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Como atualizar um gateway

Atualize um gateway para:

  • Implantar uma configuração de API diferente no gateway
  • Atualizar o nome de exibição
  • Atualize os rótulos.

Use o comando gcloud abaixo para atualizar um gateway existente, em que UPDATE_OPTIONS é substituído pela flag de opção e pelo valor que você quer atualizar:

gcloud api-gateway gateways update GATEWAY_ID \
  UPDATE_OPTIONS --api=API_ID --location=GCP_REGION --project=PROJECT_ID  

Por exemplo, para atualizar a configuração da API implantada no gateway, siga estas etapas:

gcloud api-gateway gateways update GATEWAY_ID \
  --api-config=NEW_CONFIG_ID --api=API_ID --location=GCP_REGION --project=PROJECT_ID 

em que NEW_CONFIG_ID especifica a nova configuração de API a ser implantada no gateway.

Para uma lista completa de sinalizações e argumentos de atualização disponíveis, consulte a referência gcloud api-gateway gateways update ou use o seguinte comando para exibir todas as opções de atualização:

gcloud api-gateway gateways update --help

Excluir um gateway

Use o seguinte comando gcloud para excluir um gateway atual:

gcloud api-gateway gateways delete GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

A seguir