Primeiros passos com o gateway de API e o App Engine

Esta página mostra como configurar o gateway de API para gerenciar e proteger um serviço de back-end do App Engine

Lista de tarefas

Ao seguir o tutorial, use a lista de tarefas abaixo. Todas as tarefas são necessárias para implantar um gateway de API para seu serviço de back-end do App Engine.

1. Criar ou selecionar um projeto do Google Cloud.
2. Se você não implantou seu próprio App Engine, implante um aplicativo de amostra. Consulte Antes de começar.
3. Ative os serviços de gateway de API obrigatórios.
4. Configure o IAP para proteger seu aplicativo. Consulte Configurar o IAP.
5. Crie um documento OpenAPI que descreva sua API e configure as rotas para seu App Engine. Consulte Como criar uma configuração de API.
6. Implante um gateway de API com a configuração de API. Consulte Como implantar um gateway de API.
7. Rastreie as atividades nos aplicativos. Consulte Como rastrear a atividade da API.
8. Evite cobranças na sua conta do Google Cloud. Consulte Limpeza.

Antes de começar

1. No console do Google Cloud, acesse a página Painel e selecione ou crie um projeto do Google Cloud.

   Ir para a página "Painel"

   Observação: se você não pretende manter os recursos criados neste tutorial, crie um novo projeto em vez de selecionar um existente. Depois de concluir esses passos, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

2. Verifique se o faturamento foi ativado para o projeto.

   Saiba como ativar o faturamento

3. Anote o ID do projeto que você quer usar neste tutorial. No restante desta página, esse ID de projeto é chamado de PROJECT_ID.

4. Faça o download e instale a Google Cloud CLI.

   Fazer o download da gcloud CLI

5. Atualize os componentesgcloud:

   gcloud components update

6. Defina o projeto padrão. Substitua PROJECT_ID pelo ID do projeto do Google Cloud.

   gcloud config set project PROJECT_ID

7. Se você não tiver implantado seu próprio app do App Engine, siga as etapas no Guia de início rápido do App Engine para que seu idioma use a CLI do Google Cloud para selecionar ou criar um projeto do Google Cloud e implantar um app de exemplo. Anote o URL do app, bem como a região e o ID do projeto em que o app está implantado.

Como ativar serviços obrigatórios

A API Gateway requer a ativação dos seguintes serviços do Google:

Nome	Nome
apigateway.googleapis.com	API Gateway
servicemanagement.googleapis.com	Service Management API
servicecontrol.googleapis.com	API Service Control

Para confirmar que os serviços obrigatórios estão ativados:

gcloud services list

Se você não encontrar os serviços necessários listados, ative-os:

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Para mais informações sobre os serviços do gcloud, consulte serviços gcloud.

Como configurar o IAP para proteger seu aplicativo

Para proteger seu aplicativo do App Engine, você precisa usar o Identity Aware Proxy (IAP) para garantir que as solicitações sejam autenticadas. Isso o processo inclui a especificação dos membros que devem receber o papel IAP-secured Web App User necessário para o projeto.

Siga as etapas para Ativar o IAP e verifique se você consegue fazer login no seu aplicativo.

Observação: quando o IAP estiver ativado para o aplicativo do App Engine, anote o client_id do OAuth 2.0. Ele será usado como o IAP_CLIENT_ID posteriormente neste tutorial. Para localizar o client_id do OAuth 2.0 para o app do App Engine, acesse a página APIs e serviços > Credenciais no console do Google Cloud. Copie o ID do cliente do seu aplicativo na seção IDs do cliente OAuth 2.0 da página.

Como criar uma configuração de API

Antes de usar o gateway de API para gerenciar o tráfego para o back-end implantado do App Engine, ele precisa de uma configuração de API.

Você pode criar uma configuração de API usando uma especificação OpenAPI que contenha anotações especializadas para definir o comportamento desejado do gateway de API. É necessário adicionar um campo específico do Google que contenha o URL de cada aplicativo do App Engine para que o gateway de API tenha as informações necessárias para invocar um aplicativo.

1. Crie um arquivo de texto chamado openapi2-appengine.yaml. Por conveniência, esta página refere-se ao documento do OpenAPI por esse nome de arquivo, mas é possível usar outro nome se você preferir.
2. Liste cada um dos apps na seção paths do arquivo openapi2-appengine.yaml, conforme mostrado abaixo.

   # openapi2-appengine.yaml
   swagger: '2.0'
   info:
     title: API_ID optional-string
     description: Sample API on API Gateway with an App Engine backend
     version: 1.0.0
   schemes:
     - https
   produces:
     - application/json
   paths:
     /hello:
       get:
         summary: Greet a user
         operationId: hello
         x-google-backend:
           address: APP_URL
           jwt_audience: IAP_CLIENT_ID
         responses:
           '200':
             description: A successful response
             schema:
               type: string

3. No campo title, substitua API_ID pelo nome da API e optional-string por uma breve descrição de sua escolha. Se a API ainda não existir, o comando para criar a configuração da API também criará a API com o nome especificado. O valor do campo title é usado ao produzir chaves de API que concedem acesso a essa API. Consulte os requisitos de ID da API para ver as diretrizes de nomenclatura.
4. No campo address na seção x-google-backend, substitua APP_URL pelo URL real do seu serviço do App Engine (o caminho completo da API chamada). Por exemplo, https://myapp.an.r.appspot.com/hello.

   Substitua IAP_CLIENT_ID pelo ID do cliente OAuth criado quando você configurou o IAP.

5. Digite o seguinte comando:
   • CONFIG_ID especifica o nome da configuração da API;
   • API_ID especifica o nome da sua API; Se a API ainda não existir, este comando a criará.
   • PROJECT_ID é o nome do projeto do Google Cloud.
   • SERVICE_ACCOUNT_EMAIL especifica a conta de serviço usada para assinar tokens de back-ends com autenticação configurada.

   gcloud api-gateway api-configs create CONFIG_ID \
     --api=API_ID --openapi-spec=openapi2-appengine.yaml \
     --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

   Essa operação pode levar vários minutos para ser concluída conforme a configuração da API é propagada para os sistemas downstream. A criação de uma configuração de API complexa pode levar até dez minutos para ser concluída.

6. Depois que a configuração da API for criada, execute o comando a seguir para ver os detalhes:

   gcloud api-gateway api-configs describe CONFIG_ID \
     --api=API_ID --project=PROJECT_ID

Como implantar um gateway de API

Agora é possível implantar a API no gateway de API. A implantação de uma API no gateway de API também define um URL externo para os clientes da API acessarem sua API.

Execute o comando a seguir para implantar a configuração da API que você acabou de criar no gateway de API:

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 nome do gateway.
• API_ID especifica o nome da API Gateway associada à API.
• CONFIG_ID especifica o nome da configuração da API implantada no gateway;

• GCP_REGION é a região do Google Cloud do 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 é o nome do projeto do Google Cloud.

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

Observe o valor da propriedade defaultHostname na saída deste comando. Esta é a parte do nome do host do URL do gateway que você usará para testar a implantação na próxima etapa.

Como testar sua implantação de API

Agora é possível enviar solicitações para a API usando o URL gerado durante a implantação do gateway.

Digite o seguinte comando curl, em que:

• DEFAULT_HOSTNAME especifica a parte do nome do host do URL do gateway implantado. O valor de defaultHostname pode ser encontrado na saída do comando gateways describe mostrado acima.
• hello é o caminho especificado nas configurações da API;

curl https://DEFAULT_HOSTNAME/hello

Exemplo:

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

Você verá esta resposta:

My-AppEngineApp: Access denied for user [e-mail] requesting https://my-project.appspot.com/helloGET. If you should have access, contact [e-mail] and include the full text of this message.

Pronto. O gateway de API está gerenciando o acesso ao serviço de back-end do App Engine. Para conceder acesso ao aplicativo do App Engine, você precisará configurar uma conta de serviço com as permissões corretas para o gateway de API

Rastrear a atividade da API

1. Confira os gráficos de atividades da API na página Gateway de API no Console do Google Cloud. Clique na sua API para ver os respectivos gráficos de atividade na página Visão geral. Talvez leve alguns instantes para a solicitação aparecer nos gráficos.

2. Verifique os registros de solicitações da API na página "Visualizador de registros". Um link para o A página Análise de registros pode ser encontrada na página Gateway de API na console do Google Cloud.

   Acessar a página "Gateway de API"

   Na página "API Gateway", faça o seguinte
   1. Selecione a API a ser visualizada.
   2. Clique na guia Details.
   3. Clique no link em Registros.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste guia de início rápido, faça o seguinte:

• Excluir gateways
• Excluir sua API

Se preferir, exclua o projeto do Google Cloud usado neste tutorial.