Implantar uma API em um gateway
Esta página descreve como implantar uma API no gateway de API.
Pré-requisitos
Antes de implantar uma API no gateway de API, faça o seguinte:
Prepare seu ambiente de desenvolvimento conforme descrito em Configurar seu ambiente de desenvolvimento.
Crie uma API, se estiver usando a Google Cloud CLI.
Observação: ao usar o Google Cloud console, essa etapa é concluída ao implantar a API, conforme descrito na seção a seguir.Crie uma especificação OpenAPI que defina sua API.
Crie uma configuração de API com base na sua definição de API.
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 aos 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. Seus clientes de API usam um URL no formato a seguir 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, siga estas etapas:
Google Cloud Console do
No Google Cloud console do, acesse a página Gateway de API.
- Clique em Criar gateway.
A página Criar gateway é exibida.
- Em Selecionar uma API, selecione Criar nova API no campo Selecionar uma API.
- No campo Nome de exibição, insira o nome de exibição da API.
- No campo ID da API, insira o ID da API. Consulte os requisitos de ID da API para ver as diretrizes de nomenclatura.
- (Opcional) Adicione rótulos à API.
- Na seção Configuração da API, selecione Criar uma nova configuração de API no campo Selecionar uma configuração.
- No campo Fazer upload de uma especificação de API, faça upload de um arquivo
.yamlou.json. Consulte os formatos de arquivo OpenAPI 2.0 e OpenAPI 3.x para definição de API. - No campo Nome de exibição, insira o nome de exibição da configuração da API.
- Na lista Selecionar uma conta de serviço, selecione a conta de serviço necessária. Essa conta de serviço será usada pelo gateway de API como identidade.
- (Opcional) Adicione rótulos à configuração da API.
- Na seção Detalhes do gateway, insira um nome de exibição para o gateway.
- No campo Local, selecione a Google Cloud região em que você quer implantar o gateway.
- (Opcional) Adicione rótulos ao gateway de API.
- Clique em Criar gateway.
A API recém-criada fica visível na página inicial do gateway de API.
Google Cloud CLI
Valide o ID do projeto retornado do seguinte comando para garantir que o gateway 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 Google Cloud ID do projeto em que você quer criar o serviço:
gcloud config set project PROJECT_ID
Veja a ajuda do comando
gateway create:gcloud api-gateway gateways create --help
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 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 o local do Cloud para o gateway implantado;
Durante a criação do gateway, a CLI gcloud gera informações para o terminal.
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 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 UI. 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.
Listar gateways
Esta seção explica como visualizar uma lista de todos os gateways implantados no seu Google Cloud projeto.
Google Cloud Console do
No Google Cloud console do, acesse a página Gateway de API > Gateways.
Google Cloud CLI
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 o ID da região e do gateway para receber 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
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.
Google Cloud Console do
Consulte as etapas a seguir para atualizar os detalhes do gateway de API:
No Google Cloud console do, acesse a página Gateway de API.
- Clique na API necessária.
- Clique na guia Gateways.
- Clique no gateway necessário.
- Clique em edit Editar.
- Edite o Nome de exibição ou os Rótulos.
- Selecione a Configuração de API necessária ou clique em Criar nova configuração de API e crie a configuração conforme descrito em Criar uma configuração de API.
- Clique em Atualizar.
- Clique em para retornar à página da lista de gateways.
- Na página da lista de gateways, você pode conferir o gateway atualizado.
Google Cloud CLI
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 de atualização de gateways do 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
Esta seção descreve como excluir um gateway de API atual. Siga estas etapas para remover permanentemente um gateway e a configuração associada dele do seu Google Cloud projeto.
Google Cloud Console do
-
No Google Cloud console do, acesse a página Gateway de API > Gateways.
- Clique em Mais e em Excluir para excluir o gateway de API escolhido.
Google Cloud CLI
Use o seguinte comando da CLI gcloud para excluir um gateway atual:
gcloud api-gateway gateways delete GATEWAY_ID \ --location=GCP_REGION