Primeiros passos com o Endpoints no Cloud Functions

Esta página mostra como configurar o Cloud Endpoints para Cloud Functions. O Endpoints usa o Extensible Service Proxy V2 Beta (ESPv2 Beta) como um gateway de API. Para fornecer o gerenciamento de APIs do Cloud Functions, implante o contêiner pré-construído do ESPv2 Beta para Cloud Run. Em seguida, proteja suas funções usando o IAM do Cloud Functions para que o ESPv2 Beta possa invocá-las.

Com essa configuração, o ESPv2 Beta intercepta todas as solicitações para suas funções e realiza todas as verificações necessárias (como autenticação) antes de invocar a função. Quando a função responde, o ESPv2 Beta coleta e informa telemetria. É possível visualizar métricas para sua função na página Endpoints > Serviços no Console do Google Cloud.

Para uma visão geral do Cloud Endpoints, consulte Sobre o Endpoints e Arquitetura do Endpoints.

Lista de tarefas

Ao seguir o tutorial, use a lista de tarefas abaixo. Todas as tarefas são necessárias para concluir este tutorial.

  1. Crie um projeto do Google Cloud e, se você não tiver implantado seu próprio Cloud Functions, implante uma função de exemplo. Consulte Antes de começar.
  2. Implante o contêiner do ESPv2 Beta no Cloud Run. Consulte Como implantar o ESPv2 Beta.
  3. Crie um documento do OpenAPI que descreva sua API e configure as rotas para suas Funções do Cloud. Consulte Como configurar o Endpoints.
  4. Implante o documento do OpenAPI para criar um serviço gerenciado. Consulte Como implantar a configuração do Endpoints.
  5. Crie e implante uma nova imagem do Docker do ESPv2 Beta com a configuração do serviço do Endpoints. Em seguida, conceda ao ESPv2 Beta a permissão do Cloud Identity and Access Management (Cloud IAM) para invocar suas funções. Consulte Como criar uma nova imagem do ESPv2 Beta.
  6. Invoque uma função. Consulte Como enviar uma solicitação à API.
  7. Rastreie a atividade para suas funções. Consulte Como rastrear atividade da API.
  8. Evite cobranças na sua conta do Google Cloud. Consulte Limpeza.

Antes de começar

Como o Endpoints para Cloud Functions está na versão beta, recomendamos que você siga as etapas a seguir:

  • Crie um novo projeto do Google Cloud para usar quando implantar o recipiente do ESPv2 Beta no Cloud Run.

  • Crie um novo projeto ou selecione um existente para o Cloud Functions

Para configurar:

  1. No Console do Cloud, acesse a página Gerenciar recursos e crie um projeto.

    Acessar a página Gerenciar recursos

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

    Saiba como ativar o faturamento

  3. Anote o ID do projeto, porque ele será necessário mais tarde. No restante desta página, esse ID de projeto é chamado de ESP_PROJECT_ID.

  4. Anote o número do projeto, porque ele será necessário mais tarde. No restante desta página, esse número de projeto é chamado de ESP_PROJECT_NUMBER.

  5. Faça o download do SDK do Cloud e instale-o.

    Fazer o download do Cloud SDK

  6. Se você não tiver implantado seu Cloud Functions, siga as etapas em Guia de início rápido: como usar a ferramenta de linha de comando gcloud para selecionar ou criar um projeto do Google Cloud e implantar uma função de exemplo. Anote a região e o ID do projeto em que suas funções são implantadas. No restante desta página, esse ID do projeto é chamado de FUNCTIONS_PROJECT_ID.

Como implantar o ESPv2 Beta

Para implantar o contêiner do ESPv2 Beta no Cloud Run:

  1. Verifique se o SDK do Cloud tem autorização para acessar seus dados e serviços:
    1. Faça login.
      gcloud auth login
    2. Na nova guia do navegador que é aberta, escolha uma conta que tenha o papel Editor ou Proprietário no projeto do Google Cloud que você criou para implantar o ESPv2 Beta no Cloud Run.
  2. Defina a região.
    gcloud config set run/region us-central1
  3. Implante o ESPv2 Beta no Cloud Run. Substitua CLOUD_RUN_SERVICE_NAME pelo nome do serviço que você quer usar.
    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
        --image="gcr.io/endpoints-release/endpoints-runtime-serverless:2" \
        --allow-unauthenticated \
        --platform managed \
        --project=ESP_PROJECT_ID
    

    Após a conclusão, o comando exibirá uma mensagem semelhante à seguinte:

    Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

    Por exemplo, se você definir CLOUD_RUN_SERVICE_NAME para gateway:

    Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

    Neste exemplo, https://gateway-12345-uc.a.run.app é o CLOUD_RUN_SERVICE_URL e gateway-12345-uc.a.run.app é o CLOUD_RUN_HOSTNAME.

  4. Anote o nome do host na URL retornada. Você especifica o nome do host no campo host do documento da OpenAPI.
  5. Seu serviço do Cloud Run é público na Internet. Se você quiser adicionar recursos de autenticação, recomendamos usar um dos métodos de autenticação aceitos pelo Endpoints.

Como configurar o Endpoints

É necessário ter um documento OpenAPI baseado na Especificação OpenAPI v2.0 que descreva a superfície de suas funções e quaisquer requisitos de autenticação. Você também precisa adicionar um campo específico do Google que contenha a URL de cada função para que o ESPv2 Beta tenha as informações necessárias para invocar uma função. Se você é novo na OpenAPI, consulte a visão geral da OpenAPI para ver mais informações

  1. Crie um arquivo de texto chamado openapi-functions.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. Cada uma de suas funções deve ser listada na seção paths do arquivo openapi-functions.yaml. Exemplo:
    swagger: '2.0'
    info:
      title: Cloud Endpoints + GCF
      description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
      version: 1.0.0
    host: HOST
    schemes:
      - https
    produces:
      - application/json
    paths:
      /hello:
        get:
          summary: Greet a user
          operationId: hello
          x-google-backend:
            address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/helloGET
          responses:
            '200':
              description: A successful response
              schema:
                type: string
    
    O recuo é importante para o formato yaml. Por exemplo, o campo host deve estar no mesmo nível de info.
  3. No campo address na seção x-google-backend, substitua REGION pela região do Google Cloud em que sua função está localizada e FUNCTIONS_PROJECT_ID com seu ID do projeto do Google Cloud.
  4. No campo host, especifique CLOUD_RUN_HOSTNAME, a parte do nome do host do URL que o Cloud Run criou quando você implementou o ESPv2 Beta acima em Implantar o ESPv2 Beta. Não inclua o identificador de protocolo, https://. Exemplo:

    swagger: '2.0'
      info:
        title: Cloud Endpoints + GCF
        description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
        version: 1.0.0
      host: gateway-12345-uc.a.run.app
    
  5. Anote o valor da propriedade title no arquivo openapi-functions.yaml:

    title: Cloud Endpoints + GCF

    O valor da propriedade title se tornará o nome do serviço do Endpoints depois que você implantar a configuração.

  6. Salve o documento do OpenAPI.

Para mais informações sobre os campos no documento da OpenAPI exigido pelo Endpoints, consulte Como configurar o Endpoints.

Como implantar a configuração do Endpoints

Para implantar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Ele utiliza o Service Management para criar um serviço gerenciado.

Para implantar a configuração do Endpoints:

  1. Verifique se você está no diretório que contém o documento do OpenAPI.
  2. Faça upload da configuração e crie um serviço gerenciado:

    gcloud endpoints services deploy openapi-functions.yaml \
        --project ESP_PROJECT_ID

    Isso cria um novo serviço do Endpoints com o nome especificado no campo host do arquivo openapi-functions.yaml. O serviço é configurado de acordo com o documento da OpenAPI.

    Durante a criação e a configuração do serviço, o Service Management envia informações ao terminal. Quando a implantação for concluída, será exibida uma mensagem parecida com esta:

    Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]

    CONFIG_ID é o ID de configuração exclusivo do serviço do Endpoints criado pela implantação. Exemplo:

    Service Configuration [2019-02-01-r0] uploaded for service [gateway-12345-uc.a.run.app]

    O ID de configuração do serviço consiste em um carimbo de data e um número de revisão. Se você implantar openapi-functions.yaml novamente no mesmo dia, o número de revisão será incrementado no ID de configuração do serviço. É possível visualizar a configuração do serviço e o histórico de implantação na página Endpoints > Serviços no Console do Cloud.

    Se você receber uma mensagem de erro, consulte Como solucionar problemas de implantação na configuração do Endpoints.

Como verificar os serviços obrigatórios

O Endpoints e o ESP exigem, no mínimo, os seguintes serviços:
Nome Título
servicemanagement.googleapis.com API Service Management
servicecontrol.googleapis.com API Service Control
endpoints.googleapis.com Google Cloud Endpoints

Na maioria dos casos, o comando gcloud endpoints services deploy ativa os serviços necessários. No entanto, o comando gcloud é concluído com êxito, mas não ativa os serviços necessários nas seguintes circunstâncias:

  • Você usou um aplicativo de terceiros, como o Terraform, e não incluiu esses serviços.

  • Você implantou a configuração do Endpoints em um projeto atual do Google Cloud no qual esses serviços foram desativados explicitamente.

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

gcloud services list

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

gcloud services enable SERVICE_NAME

Substitua SERVICE_NAME pelo nome do serviço a ser ativado.

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

Como criar uma nova imagem do ESPv2 Beta

Crie a configuração do serviço do Endpoints em uma nova imagem docker do ESPv2 Beta e reimplemente o serviço Cloud Run do ESPv2 Beta com a imagem. Em seguida, conceda ao ESPv2 Beta a permissão do Cloud IAM para invocar suas funções.

Para criar a configuração do serviço em uma nova imagem docker do ESPv2 Beta:

  1. Faça o download deste script em seu host local com o SDK do gcloud instalado e execute-o como:

    chmod +x gcloud_build_image
    ./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
        -c CONFIG_ID -p ESP_PROJECT_ID

    Para CLOUD_RUN_HOSTNAME, especifique o nome do host do CLOUD_RUN_SERVICE_URL, o URL que o Cloud Run criou quando você implementou o ESPv2 Beta acima em Como implementar o ESPv2 Beta. Não inclua o identificador de protocolo, https://.

    Exemplo:

    chmod +x gcloud_build_image
    ./gcloud_build_image -s gateway-12345-uc.a.run.app \
        -c 2019-02-01-r0 -p ESP_PROJECT_ID

    O script usa o comando gcloud para fazer o download da configuração do serviço, criar a configuração de serviço em uma nova imagem do ESPv2 Beta e fazer upload da nova imagem para o registro de contêiner do projeto localizado aqui:

    gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID

    Exemplo:

    gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:gateway-12345-uc.a.run.app-2019-02-01-r0"
  2. Implante novamente o serviço Cloud Run do ESPv2 Beta com a nova imagem. Substitua CLOUD_RUN_SERVICE_NAME com o mesmo nome de serviço do Cloud Run que você usou quando implantou-o originalmente em Como implantar o ESPv2 Beta:

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
      --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
      --allow-unauthenticated \
      --platform managed \
      --project=ESP_PROJECT_ID
  3. Se você quiser configurar o Endpoints para usar opções adicionais de inicialização do ESPv2 Beta, como ativar o CORS por exemplo, passe os argumentos na variável de ambiente ESPv2_ARGS:

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
      --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
      --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
      --allow-unauthenticated \
      --platform managed \
      --project ESP_PROJECT_ID

    Para obter mais informações e exemplos sobre como configurar a variável de ambiente ESPv2_ARGS, incluindo a lista de opções disponíveis e informações sobre como especificar várias opções, consulte Sinalizações do Extensible Service Proxy V2 Beta.

  4. Conceda permissão ao ESPv2 Beta para invocar suas funções. Execute o seguinte comando para cada função. No comando a seguir:

    • Substitua FUNCTION_NAME pelo nome da sua função. Se você estiver usando a função criada no Gui de início rápido: como usar a ferramenta da linha de comando gcloud, use helloGET como esse valor.
    • Substitua ESP_PROJECT_NUMBER pelo número do projeto do projeto criado para o ESPv2 Beta. Uma maneira de encontrar isso é acessando o Console do IAM e encontrar a conta de serviço de computação padrão, que é a conta de serviço usada na sinalização member.
    gcloud functions add-iam-policy-binding FUNCTION_NAME \
       --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
       --role "roles/cloudfunctions.invoker" \
       --project FUNCTIONS_PROJECT_ID

Para mais informações, consulte Como gerenciar o acesso por meio do Cloud IAM.

Como enviar solicitações à API

Veja nesta seção como enviar solicitações para a API.

  1. Crie uma variável de ambiente para o nome do serviço do Endpoints. Este é o nome que você especificou no campo host do documento da OpenAPI. Por exemplo:
    • Linux ou macOS:

      export ENDPOINTS_HOST=gateway-12345-uc.a.run.app

    • Windows PowerShell:

      $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

Linux ou Mac OS

Use curl para enviar uma solicitação HTTP usando a variável de ambiente ENDPOINTS_HOST definida na etapa anterior.

curl --request GET \
   --header "content-type:application/json" \
   "https://${ENDPOINTS_HOST}/hello"

PowerShell

Use Invoke-WebRequest para enviar uma solicitação HTTP usando a variável de ambiente ENDPOINTS_HOST definida na etapa anterior.

(Invoke-WebRequest -Method GET `
    -Headers @{"content-type"="application/json"} `
    -URI "https://$Env:ENDPOINTS_HOST/hello").Content

No exemplo acima, as duas primeiras linhas terminam em um acento grave. Quando você colar o exemplo no PowerShell, verifique se não há espaço após os acentos graves. Para informações sobre as opções usadas na solicitação de exemplo, consulte Invoke-WebRequest (em inglês) na documentação da Microsoft.

Aplicativo de terceiros

É possível usar um aplicativo de terceiros, como a solicitação da extensão Postman (em inglês) do navegador Google Chrome.

  • Selecione GET como o verbo HTTP.
  • Para o cabeçalho, selecione a chave content-type e o valor application/json.
  • Use o URL real em vez da variável de ambiente, por exemplo:

    https://gateway-12345-uc.a.run.app/hello
    

Se não receber uma resposta bem-sucedida, consulte Como solucionar problemas em erros de resposta.

Você acaba de implantar e testar uma API no Endpoints.

Como rastrear atividade da API

  1. Visualize os gráficos de atividades da sua API na página Endpoints > Serviço no Console do Cloud.

    Ver gráficos de atividades do Endpoints

    Pode levar alguns instantes até a solicitação aparecer nos gráficos.

  2. Verifique os registros de solicitações da API na página "Visualizador de registros".

    Ver registros de solicitações do Endpoints

Como criar um portal do desenvolvedor para a API

É possível usar o Portal do Cloud Endpoints para criar um portal do desenvolvedor, um site para interagir com a API de amostra. Para saber mais, consulte a Visão geral do Portal do Cloud Endpoints.

Limpeza

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste guia de início rápido, siga estas etapas:

Consulte Como excluir uma API e as instâncias relacionadas para mais informações sobre como interromper os serviços usados neste tutorial.

A seguir