Introdução ao API Gateway e ao App Engine

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

Lista de tarefas

Use a seguinte lista de tarefas enquanto segue o tutorial. Todas as tarefas são necessárias para implementar um gateway de API para o serviço de back-end do App Engine.

  1. Crie ou selecione um Google Cloud projeto.
  2. Se ainda não implementou o seu próprio App Engine, implemente uma app de exemplo. Consulte a secção Antes de começar.
  3. Ative os serviços de gateway da API necessários.
  4. Configure as CNAs para proteger a sua app. Consulte o artigo Configure as CNAs.
  5. Crie uma descrição OpenAPI que descreva a sua API e configure as rotas para o App Engine. Consulte o artigo Crie uma configuração de API.
  6. Implemente um gateway de API através da configuração da API. Consulte o artigo Implementar um gateway da API.
  7. Monitorize a atividade nas suas apps. Consulte o artigo Acompanhamento da atividade da API.
  8. Evite incorrer em cobranças na sua conta Google Cloud . Consulte Limpar.

Antes de começar

  1. Na Google Cloud consola, aceda à página Painel de controlo e selecione ou crie um Google Cloud projeto.

    Aceder à página Painel de controlo

  2. Certifique-se de que a faturação está ativada para o seu projeto.

    Ative a faturação

  3. Tome nota do ID do projeto que quer usar para este tutorial. No resto desta página, este ID do projeto é designado por PROJECT_ID.

  4. Transfira e instale a Google Cloud CLI.

    Transfira a CLI gcloud

  5. Atualize os gcloudcomponentes:

    gcloud components update

  6. Defina o projeto predefinido. Substitua PROJECT_ID pelo seu Google Cloud ID do projeto:

    gcloud config set project PROJECT_ID

  7. Se não implementou a sua própria app do App Engine, siga os passos no Início rápido do App Engine para o seu idioma de modo a usar a CLI Google Cloud para selecionar ou criar um Google Cloud projeto e implementar uma app de exemplo. Tome nota do URL da app, bem como da região e do ID do projeto onde a sua app está implementada.

Ative os serviços necessários

O API Gateway requer que ative os seguintes serviços Google:

Nome Título
apigateway.googleapis.com API do API Gateway
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

Use os seguintes comandos para ativar estes 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 gcloud, consulte os serviços gcloud.

Configure a IAP para proteger a sua app

Para proteger a sua app do App Engine, tem de usar o Identity Aware Proxy (IAP) para verificar se os pedidos estão autenticados. Este processo inclui a especificação dos membros aos quais deve ser atribuída a função IAP-secured Web App User necessária para o projeto.

Siga os passos para ativar as CAsI e verifique se consegue iniciar sessão na sua aplicação.

Crie uma configuração de API

Antes de poder usar o API Gateway para gerir o tráfego para o seu back-end do App Engine implementado, precisa de uma configuração da API.

Pode criar uma configuração da API através de uma descrição OpenAPI que contenha anotações especializadas para definir o comportamento escolhido do API Gateway. Tem de adicionar um campo específico da Google que contenha o URL de cada app do App Engine para que o API Gateway tenha as informações necessárias para invocar uma app.

Para mais detalhes sobre as extensões OpenAPI suportadas, consulte o seguinte:

Para criar a configuração da API:

  1. Crie um ficheiro de texto denominado openapi-appengine.yaml. Para maior conveniência, esta página refere-se à descrição da OpenAPI por esse nome de ficheiro, mas pode atribuir-lhe outro nome, se preferir.
  2. Copie o conteúdo do seguinte ficheiro para o ficheiro 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 sua API e substitua optional-string por uma breve descrição à sua escolha. Se a API ainda não existir, o comando para criar a configuração da API também cria a API com o nome que especificar. O valor do campo title é usado quando são geradas chaves de API que concedem acesso a esta API. Consulte os requisitos de ID da API para ver as diretrizes de nomenclatura da API.
    • No campo address da secçã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 de cliente OAuth que criou quando configurou a 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 sua API e substitua optional-string por uma breve descrição à sua escolha. Se a API ainda não existir, o comando para criar a configuração da API também cria a API com o nome que especificar. O valor do campo title é usado quando são geradas chaves de API que concedem acesso a esta API. Consulte os requisitos de ID da API para ver as diretrizes de nomenclatura da API.
    • 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 de cliente OAuth que criou quando configurou as CAs.
  3. Introduza o seguinte comando, em que:
    • 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 cria-a.
    • 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

    Esta operação pode demorar vários minutos a ser concluída, uma vez que a configuração da API é propagada para sistemas a jusante. A criação de uma configuração de API complexa pode demorar até dez minutos a ser concluída com êxito.

  4. Depois de criar a configuração da API, pode ver os respetivos detalhes executando este comando: 
    gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID

Implementar um gateway da API

Agora, pode implementar a sua API no API Gateway. A implementação de uma API no API Gateway também define um URL externo que os clientes API podem usar para aceder à sua API.

Execute o seguinte comando para implementar a configuração da API que acabou de criar no API Gateway:

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION

Onde:

  • GATEWAY_ID especifica o nome da gateway.
  • API_ID especifica o nome da API do gateway da API associada a este gateway.
  • CONFIG_ID especifica o nome da configuração da API implementada no gateway.

  • GCP_REGION é a Google Cloud região para o gateway implementado.

Após a conclusão com êxito, pode usar o seguinte comando para ver detalhes sobre o gateway:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION

Anote o valor da propriedade defaultHostname no resultado deste comando. Esta é a parte do nome do anfitrião do URL do gateway que usa para testar a implementação no passo seguinte.

Testar a implementação da API

Agora, pode enviar pedidos para a sua API através do URL gerado após a implementação da gateway.

Introduza o seguinte comando curl, em que:

  • DEFAULT_HOSTNAME especifica a parte do nome do anfitrião do URL da gateway implementada. Pode encontrar o valor de defaultHostname no resultado do comando gateways describe apresentado anteriormente.
  • DEFAULT_HOSTNAME especifica a parte do nome do anfitrião do URL da gateway implementada. Pode encontrar o valor de defaultHostname no resultado do comando gateways describe apresentado anteriormente.
  • hello é o caminho especificado na configuração da API.
curl https://DEFAULT_HOSTNAME/hello

Por exemplo: 

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

Deverá ver o seguinte resultado:

My-AppEngineApp: Access denied for user gateway-1a2b3c@04d5e6f35FgdsT73dFrty-tp.iam.gserviceaccount.com requesting https://my-project.appspot.com/helloGET. If you should have access, contact myldap@google.com and include the full text of this message.

Êxito! O gateway está a gerir o acesso ao serviço de back-end do App Engine. Para conceder acesso à sua app do App Engine, tem de configurar uma conta de serviço com as autorizações corretas para a sua entrada.

Acompanhamento da atividade da API

  1. Veja os gráficos de atividade da sua API na página API Gateway na Google Cloud consola. Clique na sua API para ver os respetivos gráficos de atividade na página Vista geral. Os pedidos podem demorar alguns momentos a ser refletidos nos gráficos.

  2. Consulte os registos de pedidos da sua API na página Explorador de registos. Pode encontrar um link para a página do Explorador de registos na página do API Gateway na Google Cloud consola.

    Aceda à página do API Gateway

    Depois de aceder à página do API Gateway:

    1. Selecione a API para ver.
    2. Clique no separador Detalhes.
    3. Clique no link em Registos.

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste início rápido, pode:

Em alternativa, também pode eliminar o Google Cloud projeto usado para este tutorial.