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. 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 Cloud, acesse a página Painel e selecione ou crie um projeto do Google Cloud.

    Ir para a página "Painel"

  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 do SDK do Cloud e instale-o.

    Fazer o download do Cloud SDK

  5. Atualize os componentes gcloud:

    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 implantou seu próprio aplicativo do App Engine, siga as etapas no Guia de início rápido do App Engine para sua linguagem a fim de usar a ferramenta de linha de comando gcloud para selecionar ou criar um projeto do Google Cloud e implantar um aplicativo de amostra. Anote o URL do aplicativo, a região e o ID do projeto em que seu aplicativo 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.

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

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 e IAP_CLIENT_ID pelo ID do cliente OAuth que você criou quando 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 criada explicitamente para a criação de configurações de API.
    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.

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

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

Como rastrear a atividade da API

  1. Veja os gráficos de atividades da API na página Gateway de API no Console do 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". O link para a página do Explorador de registros pode ser encontrado na página do Gateway de API no Console do 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, exclua a API e os gateways. Também é possível excluir o projeto do Google Cloud usado neste tutorial.