Criar e implantar uma função HTTP do Cloud Run usando o Go (1ª geração)

Este guia explica o processo de criação de uma função do Cloud Run usando o ambiente de execução do Go. Há dois tipos de funções do Cloud Run:

• Uma função HTTP, que você invoca a partir de solicitações HTTP padrão.
• Uma função direcionada a eventos, que você usa para processar eventos da infraestrutura do Cloud, como mensagens em um tópico do Pub/Sub ou alterações em um bucket do Cloud Storage.

O exemplo mostra como criar uma função HTTP simples.

Saiba mais: para mais detalhes, leia sobre funções HTTP e funções orientadas a eventos.

Antes de começar

Faça login na sua Google Cloud conta do. Se você é novo no Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em cenários reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

Instale a Google Cloud CLI.

Observação: se você já tiver instalado a CLI gcloud anteriormente, verifique se você tem a versão mais recente executando gcloud components update.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, você precisa do papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um Google Cloud projeto:

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o Google Cloud projeto que você está criando.

• Selecione o Google Cloud projeto que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do Google Cloud projeto.

Verifique se o faturamento está ativado para o Google Cloud projeto.

Ative as APIs Cloud Functions e Cloud Build:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador de Service Usage role (roles/serviceusage.serviceUsageAdmin), que contém a serviceusage.services.enable permissão. Saiba como conceder papéis.

gcloud services enable cloudfunctions cloudbuild.googleapis.com

Instale a Google Cloud CLI.

Observação: se você já tiver instalado a CLI gcloud anteriormente, verifique se você tem a versão mais recente executando gcloud components update.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: a seleção de um projeto não exige um papel específico do IAM. Você pode selecionar qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, você precisa do papel de criador de projetos (roles/resourcemanager.projectCreator), que contém a resourcemanager.projects.create permissão. Saiba como conceder papéis.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

• Crie um Google Cloud projeto:

  gcloud projects create PROJECT_ID

  Substitua PROJECT_ID por um nome para o Google Cloud projeto que você está criando.

• Selecione o Google Cloud projeto que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do Google Cloud projeto.

Verifique se o faturamento está ativado para o Google Cloud projeto.

Ative as APIs Cloud Functions e Cloud Build:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador de Service Usage role (roles/serviceusage.serviceUsageAdmin), que contém a serviceusage.services.enable permissão. Saiba como conceder papéis.

gcloud services enable cloudfunctions cloudbuild.googleapis.com

1. Prepare seu ambiente de desenvolvimento.

   Acesse o guia de configuração do Go

crie uma função

1. Crie um diretório no seu sistema local para o código de função:

   Linux ou macOS

   mkdir ~/helloworld
   cd ~/helloworld
   

   Windows

   mkdir %HOMEPATH%\helloworld
   cd %HOMEPATH%\helloworld
   

2. Crie um arquivo chamado hello_http.go no diretório helloworld com o seguinte conteúdo:

   
   // Package helloworld provides a set of Cloud Functions samples.
   package helloworld
   
   import (
   	"encoding/json"
   	"fmt"
   	"html"
   	"net/http"
   
   	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
   )
   
   func init() {
   	functions.HTTP("HelloHTTP", HelloHTTP)
   }
   
   // HelloHTTP is an HTTP Cloud Function with a request parameter.
   func HelloHTTP(w http.ResponseWriter, r *http.Request) {
   	var d struct {
   		Name string `json:"name"`
   	}
   	if err := json.NewDecoder(r.Body).Decode(&d); err != nil {
   		fmt.Fprint(w, "Hello, World!")
   		return
   	}
   	if d.Name == "" {
   		fmt.Fprint(w, "Hello, World!")
   		return
   	}
   	fmt.Fprintf(w, "Hello, %s!", html.EscapeString(d.Name))
   }
   

   Esse exemplo de função recebe um nome fornecido na solicitação HTTP e retorna uma saudação, ou "Hello, World!", quando nenhum nome é fornecido.

Especificar as dependências

Esta função de exemplo usa apenas pacotes da biblioteca padrão do Go. Assim, você não precisa declarar nenhuma dependência além de apenas importar os pacotes.

Para funções que exigem dependências fora da biblioteca padrão, é necessário fornecer as dependências por meio de um arquivo go.mod ou um diretório vendor. Para ver mais detalhes, leia Como especificar dependências no Go.

Implantar a função

Para implantar a função com um gatilho HTTP, execute o seguinte comando no diretório helloworld, especificando go113 ou go111 como o valor para a sinalização --runtime, dependendo da versão usada:

gcloud functions deploy HelloHTTP --no-gen2 --runtime go121 --trigger-http --allow-unauthenticated

Observação: o Cloud Run functions procura funções implantáveis no diretório atual do seu terminal por padrão. Use a flag --source ao implantar a função via gcloud para especificar um diretório de origem de função diferente.

A sinalização --allow-unauthenticated permite que você atinja a função sem autenticação. Para exigir autenticação, omita a sinalização.

Saiba mais: para ver mais detalhes, leia sobre Como implantar Cloud Run functions.

Testar a função

1. Quando a implantação da função estiver concluída, anote a propriedade httpsTrigger.url ou encontre-a usando o seguinte comando:

   gcloud functions describe HelloHTTP
   

   A aparência será semelhante a esta:

   https://GCP_REGION-PROJECT_ID.cloudfunctions.net/HelloHTTP

2. Visite este URL em seu navegador ou use cURL executando o comando:

   curl https://GCP_REGION-PROJECT_ID.cloudfunctions.net/HelloHTTP

   Você verá uma mensagem "Hello World!". Tente passar um nome na solicitação HTTP executando o seguinte comando:

   curl -X POST https://GCP_REGION-PROJECT_ID.cloudfunctions.net/HelloHTTP -H "Content-Type:application/json"  -d '{"name":"NAME"}'

   Você verá uma mensagem "Hello, NAME!"

Ver registros

Os registros do Cloud Run functions são visíveis usando a CLI do Google Cloud e na interface do Cloud Logging.

Usar a ferramenta de linha de comando

Para ver os registros da função com a CLI gcloud, use o logs read comando, seguido por o nome da função:

gcloud functions logs read HelloHTTP

A saída será semelhante a esta:

LEVEL  NAME        EXECUTION_ID  TIME_UTC                 LOG
D      HelloHTTP  buv9ej2k1a7r  2019-09-20 13:23:18.910  Function execution started
D      HelloHTTP  buv9ej2k1a7r  2019-09-20 13:23:18.913  Function execution took 4 ms, finished with status code: 200

Observação: normalmente há um pequeno atraso entre o momento em que as entradas de registro são criadas e quando elas são exibidas no Cloud Logging.

Usar o painel do Logging

Também é possível ver os registros do Cloud Run functions no Google Cloud console.

Saiba mais: para ver mais detalhes, leia sobre como gravar, ver e responder a registros.