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:
Prepare seu ambiente de desenvolvimento conforme descrito em Configurar o ambiente de desenvolvimento.
Crie uma API, se estiver usando a Google Cloud CLI.
Observação: ao usar o console Google Cloud , esta etapa é concluída ao implantar a API, conforme descrito abaixo.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 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.
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 o 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
No console do Google Cloud , acesse a página Gateway de API.
- Clique em Criar gateway.
A página Criar gateway é exibida.
- Em Selecionar uma API, escolha Criar nova 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 da API no campo Selecionar uma configuração.
- No campo Fazer upload de uma especificação de API, envie 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 de API.
- 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.
- (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 região Google Cloud 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 API Gateway.
CLI do Google Cloud
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 mudar o projeto padrão, execute o seguinte comando e substitua PROJECT_ID pelo ID do projeto Google Cloud 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 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 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 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.
Listar gateways
Nesta seção, explicamos como conferir uma lista de todos os gateways de API implantados no seu projeto Google Cloud .
Console do Google Cloud
No console do Google Cloud , acesse a página Gateway de API > 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 o ID 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
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 gateway de API:
No console do Google Cloud , 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 Marcadores.
- Selecione a configuração de API necessária ou clique em Criar nova configuração de API e crie a configuração conforme mostrado aqui.
- Clique em Atualizar.
- Clique em para voltar à página da lista de gateways.
- 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, em que UPDATE_OPTIONS é substituído pela flag de opção e pelo valor do 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 argumentos e flags 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 do seu projeto Google Cloud .
Console do Google Cloud
-
No console do Google Cloud , acesse a página Gateway de API > Gateways.
- 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