Primeiros passos com o gateway de API e o App Engine

Nesta página, mostramos como configurar um 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. Crie ou selecione 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 uma descrição do OpenAPI que descreva sua API e configure as rotas para seu App Engine. Consulte Criar uma configuração de API.
6. Implante um gateway de API usando 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. Para evitar 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.

   Ativar 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 CLI gcloud

5. Atualize os componentesgcloud:

   gcloud components update

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

   gcloud config set project PROJECT_ID

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

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

Use os seguintes comandos para ativar esses serviç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.

Configurar o IAP para proteger o aplicativo

Para proteger seu aplicativo do App Engine, você precisa usar o Identity Aware Proxy (IAP) para verificar se as solicitações são autenticadas. Esse processo inclui especificar os membros que precisam receber a função IAP-secured Web App User necessária 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 aplicativo do App Engine, acesse a página APIs e serviços > Credenciais no console Google Cloud . Copie o ID do cliente do seu aplicativo na seção IDs do cliente OAuth 2.0 da página.

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 descrição OpenAPI que contenha anotações especializadas para definir o comportamento escolhido 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.

Para mais detalhes sobre as extensões da OpenAPI compatíveis, consulte o seguinte:

• Extensões OpenAPI 2.0 no gateway de API
• Extensões OpenAPI 3.x da OpenAPI no gateway de API

Para criar a configuração da API:

1. Crie um arquivo de texto chamado openapi-appengine.yaml. Por conveniência, esta página se refere à descrição da OpenAPI por esse nome de arquivo, mas você pode nomear algo diferente, se preferir.
2. Copie o conteúdo do arquivo a seguir no seu arquivo openapi-run.yaml:

   OpenAPI 2.0

   # openapi-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

   • 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.
   • 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.

   OpenAPI 3.x

   # openapi-appengine.yaml
   openapi: 3.0.4
   info:
     title: API_ID optional-string
     description: Sample API on API Gateway with an App Engine backend
     version: 1.0.0
   # Define reusable components in x-google-api-management
   x-google-api-management:
     backends:
       appengine_backend:
         address: APP_URL
         jwtAudience: IAP_CLIENT_ID
         deadline: 30.0
         pathTranslation: APPEND_PATH_TO_ADDRESS
         protocol: "http/1.1"
   # Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
   x-google-backend: appengine_backend
   paths:
     /hello:
       get:
         summary: Greet a user
         operationId: hello
         responses:
           '200':
             description: A successful response
             schema:
               type: string

   • 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.
   • No campo address, 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.

3. 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á.
   • SERVICE_ACCOUNT_EMAIL especifica a conta de serviço usada para assinar tokens para back-ends com autenticação configurada.

   gcloud api-gateway api-configs create CONFIG_ID \
     --api=API_ID --openapi-spec=openapi2-appengine.yaml \
    --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.

4. 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 

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 

Em que:

• 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 Google Cloud região 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

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

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 anteriormente.
• 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 anteriormente.
• 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 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.

Rastrear a atividade da API

1. Veja os gráficos de atividades da API na página Gateway de API no Google Cloud console. 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". O link para a página do Explorador de registros pode ser encontrado na página do Gateway de API no console doGoogle 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 seus gateways
• Excluir sua API

Como alternativa, também é possível excluir o projeto do Google Cloud usado neste tutorial.