Implementar uma API num gateway

Pré-requisitos

Antes de poder implementar uma configuração da API no API Gateway, certifique-se de que tem:

Requisitos de ID do gateway

Muitos dos comandos gcloud apresentados abaixo requerem que especifique o ID da gateway no formato: GATEWAY_ID. O gateway da API aplica os seguintes requisitos para o ID do gateway:

  • Tem de ter um comprimento máximo de 49 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.

Definir o ponto final da configuração da API implementada

Quando implementa uma configuração da API num gateway, o API Gateway cria um URL único para o gateway no domínio gateway.dev. Os seus clientes da API usam, em seguida, um URL no formato abaixo para aceder à configuração da API implementada:

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

onde GATEWAY_ID é o nome da gateway, HASH é o código hash exclusivo gerado quando implementou a API e REGION_CODE é o código da localização na nuvem na qual implementou a gateway.

Por exemplo:

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

Implemente uma configuração de API num gateway

Use a CLI do Google Cloud para implementar uma configuração da API num gateway. Quando implementa a configuração da API, tem de especificar o nome da API. Se a entrada ainda não existir para a API, este comando também a cria.

Para implementar uma configuração da API num gateway:

  1. Valide o ID do projeto devolvido pelo seguinte comando para se certificar de que o gateway 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

  2. Veja a ajuda para o comando gateway create:

    gcloud api-gateway gateways create --help

  3. Execute o seguinte comando para implementar 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

    where:

    • GATEWAY_ID especifica o ID do novo gateway. Se o gateway ainda não existir, este comando cria-o.
    • API_ID especifica o ID da API do gateway da API associada a este gateway.
    • CONFIG_ID especifica o ID da configuração da API implementada no gateway. Tem de especificar uma configuração da API quando cria um gateway.

    • GCP_REGION especifica a localização na nuvem da entrada implementada.

    • PROJECT_ID especifica o Google Cloud ID do projeto.

    À medida que cria a entrada, o gcloud envia informações para o terminal.

  4. Após a conclusão com êxito, pode usar o seguinte comando para ver detalhes sobre o gateway:

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

    Este comando devolve 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'

    Tome nota do valor da propriedade defaultHostname. Esta é a parte do nome do anfitrião do URL do gateway. Para aceder a uma configuração da API implementada nesta entrada, usa um URL no formato:

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

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

  • --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 gateway, ou seja, o nome apresentado na IU. Não use espaços no nome. Em alternativa, use hífenes e sublinhados. O valor predefinido é GATEWAY_ID.
  • --labels=KEY1=VALUE1,KEY2=VALUE2,...: especifica as etiquetas associadas ao gateway.

Gateways de fichas

Para listar gateways de um projeto específico:

gcloud api-gateway gateways list --project=PROJECT_ID

Este comando devolve o resultado no seguinte 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

Em alternativa, 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 os IDs do projeto, da região e da gateway para obter informações detalhadas sobre a gateway, incluindo a identidade da configuração da API implementada na gateway:

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

Atualizar um gateway

Atualizar um gateway para:

  • Implemente uma configuração de API diferente no gateway
  • Atualize o nome a apresentar
  • Atualize as etiquetas

Use o seguinte comando gcloud para atualizar um gateway existente, em que UPDATE_OPTIONS é substituído pelo valor e pela opção do comando do gateway que 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 implementada no gateway:

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 da API a implementar no gateway.

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

gcloud api-gateway gateways update --help

Eliminar um gateway

Use o seguinte comando gcloud para eliminar um gateway existente:

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

O que se segue?