Implantar uma API em um gateway

Nesta página, descrevemos como implantar uma API no gateway de API.

Pré-requisitos

Antes de implantar uma API no gateway de API, faça o seguinte:

Requisitos de ID do gateway

Muitos dos comandos da CLI gcloud descritos neste documento exigem que você especifique o ID do gateway, no formato: GATEWAY_ID. O gateway de API aplica os seguintes requisitos para o ID 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.

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. Em seguida, os clientes da API usam um URL no seguinte formato 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 do local do Cloud em que você implantou o gateway.

Exemplo:

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

Implantar uma API em um gateway

Para implantar uma API em um gateway:

Console do Google Cloud

  1. No console do Google Cloud , acesse a página Gateway de API.

    Acessar o gateway de API

  2. Clique em Criar gateway.

    A página Criar gateway é exibida.

  3. Em Selecionar uma API, escolha Criar nova API.
  4. No campo Nome de exibição, insira o nome de exibição da API.
  5. No campo ID da API, insira o ID da API. Consulte os requisitos de ID da API para ver as diretrizes de nomenclatura.
  6. (Opcional) Adicione rótulos à API.
  7. Na seção Configurar API, selecione Criar uma configuração de API no campo Selecionar uma configuração.
  8. No campo Fazer upload de uma API Spec, envie um arquivo .yaml ou .json. Consulte os formatos de arquivo OpenAPI 2.0 e OpenAPI 3.x para definição de API.
  9. No campo Nome de exibição, insira o nome de exibição da configuração da API.
  10. Na lista Selecionar uma conta de serviço, escolha a conta necessária. Essa conta de serviço será usada pelo gateway de API como identidade.
  11. (Opcional) Adicione rótulos à configuração da API.
  12. Na seção Detalhes do gateway, insira um nome de exibição para o gateway.
  13. No campo Local, selecione a Google Cloud região em que você quer implantar o gateway.
  14. (Opcional) Adicione rótulos ao gateway de API.
  15. Clique em Criar gateway.

    16. A API recém-criada fica visível na página inicial do API Gateway.

CLI do Google Cloud

  1. Valide o ID do projeto retornado do seguinte comando para garantir que o gateway não seja criado no projeto errado.

    gcloud config list project

    Se você precisar mudar o projeto padrão, execute o comando a seguir e substitua PROJECT_ID pelo ID do projeto 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

    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 do gateway de API associado a esse 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 o local na nuvem para o gateway implantado.

    Enquanto o gateway é criado, a CLI gcloud envia 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

    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 gcloud aceita muitas opções, incluindo as descritas na referência da 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.
  • --enable-streaming: especifica o suporte para streaming (prévia pública). Essa é uma opção de criação e não pode ser modificada depois da criação do gateway. Se for omitido, o gateway de API vai selecionar o modo automaticamente. Se essa flag não for reconhecida, execute gcloud components update para atualizar a instalação do componente. Para mais informações, consulte Configurar o streaming.

Listar gateways

Nesta seção, explicamos como conferir uma lista de todos os gateways implantados no seu projeto Google Cloud .

Console do Google Cloud

No console do Google Cloud , acesse a página Gateway de API > Gateways.

Acessar "Gateways"

CLI do Google Cloud

Para listar gateways para um projeto específico:

gcloud api-gateway gateways list

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

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/*" \

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 os IDs da região e do gateway para receber informações detalhadas sobre o gateway, incluindo a identidade da configuração de API implantada no gateway:

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

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.

Console do Google Cloud

Siga estas etapas para atualizar os detalhes do API Gateway:

  1. No console do Google Cloud , acesse a página Gateway de API.

    Acessar o gateway de API

  2. Clique na API necessária.
  3. Clique na guia Gateways.
  4. Clique no gateway necessário.
  5. Clique em Editar Editar.
  6. Edite o Nome de exibição ou os Marcadores.
  7. Selecione a Configuração da API necessária ou clique em Criar nova configuração da API e crie a configuração conforme descrito em Como criar uma configuração de API.
  8. Clique em Atualizar.
  9. Clique em para voltar à página da lista de gateways.
  10. Na página da lista de gateways, você pode conferir o gateway atualizado.

CLI do Google Cloud

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

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

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

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

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

gcloud api-gateway gateways update --help

Excluir um gateway

Nesta seção, descrevemos como excluir um gateway de API. Siga estas etapas para remover permanentemente um gateway e a configuração associada dele do seu projeto Google Cloud .

Console do Google Cloud

  1. No console do Google Cloud , acesse a página Gateway de API > Gateways.

    Acessar "Gateways"

  2. Clique em Mais e em Excluir para excluir o gateway de API escolhido.

CLI do Google Cloud

Use o seguinte comando da CLI gcloud para excluir um gateway:

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

A seguir