Esta página foi traduzida pela API Cloud Translation.

Como implantar uma API em um gateway

Pré-requisitos

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

Prepare seu ambiente de desenvolvimento conforme descrito em Como configurar seu ambiente de desenvolvimento.
criado uma API;
criou uma definição de API;
criou uma configuração de API com base na sua definição de API;

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:

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
```

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 --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;
  Observação:
  os valores permitidos são:
  - asia-northeast1
  - australia-southeast1
  - europe-west1
  - europe-west2
  - us-east1
  - us-east4
  - us-central1
  - us-west2
  - us-west3
  - us-west4
- PROJECT_ID especifica o ID do projeto do Google Cloud.
Durante a criação do gateway, o 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 --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 do gateway 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.

Observação: há dois pontos importantes a serem considerados ao atualizar um gateway com uma nova configuração de API:

Os gateways só aceitam configurações de API criadas na mesma API. Para implantar uma configuração de API criada em outra API, crie um novo gateway ou use um que já ofereça configurações na nova API.
O gateway de API é compatível com um modelo de atualização sem inatividade. Isso significa que a API continua processando solicitações durante a implantação da configuração da API atualizada. No entanto, há um período de tempo em que a nova configuração de API está sendo implantada quando algumas solicitações ainda podem ser manipuladas pela versão anterior da configuração da API. Se você implantou a configuração da API em várias regiões e gateways, é necessário implantar novamente a configuração atualizada da API em cada região.

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

Use o seguinte comando gcloud para excluir um gateway atual:

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