Criar e implantar uma função do Cloud Run em HTTP com Go

Introduçã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 orientada a eventos, que é acionada por eventos em sua infraestrutura do Cloud, como mensagens em um tópico do Pub/Sub ou alterações em um bucket do Cloud Storage.

Para mais detalhes, leia Como escrever funções HTTP e Como escrever funções orientadas a eventos.

Antes de começar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  4. Enable the Cloud Functions, Cloud Build, Artifact Registry, Cloud Run, and Cloud Logging APIs.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  7. Enable the Cloud Functions, Cloud Build, Artifact Registry, Cloud Run, and Cloud Logging APIs.

    Enable the APIs

  8. Instale e inicialize a CLI gcloud.
  9. Atualize e instale os componentes gcloud com o comando a seguir.
    gcloud components update
  10. Prepare seu ambiente de desenvolvimento.

    Acesse o guia de configuração do Go

Criar a 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

Crie um arquivo go.mod para rastrear suas dependências:

cd ~/helloworld
go mod init example.com/hello
go mod tidy

Se a função tiver dependências além da biblioteca do framework, edite o arquivo go.mod para adicioná-las. Também é possível especificar dependências com um diretório vendor do Go. Para ver mais detalhes, leia Como especificar dependências no Go.

Criar e testar a função localmente

É possível criar e testar a função localmente sem implantá-la. Para isso, crie um módulo local main.go local para invocar a função.

  1. Crie um subdiretório cmd:

    mkdir ~/helloworld/cmd
    cd ~/helloworld/cmd
    
  2. Crie um módulo Go principal para invocar a função copiando o seguinte snippet de código em um arquivo chamado main.go no diretório ~/helloworld/cmd:

    package main
    
    import (
      "log"
      "os"
    
      // Blank-import the function package so the init() runs
      _ "example.com/hello"
      "github.com/GoogleCloudPlatform/functions-framework-go/funcframework"
    )
    
    func main() {
      // Use PORT environment variable, or default to 8080.
      port := "8080"
      if envPort := os.Getenv("PORT"); envPort != "" {
        port = envPort
      }
      if err := funcframework.Start(port); err != nil {
        log.Fatalf("funcframework.Start: %v\n", err)
      }
    }
    
  3. Resolva as dependências restantes com o comando go mod tidy:

    go mod tidy
    
  4. Execute a função localmente com o seguinte comando:

    export FUNCTION_TARGET=HelloHTTP
    go run ~/helloworld/cmd/main.go
    
  5. Acesse http://localhost:8080 em um navegador ou execute curl localhost:8080 em outra janela para testar sua função.

    Saiba mais em Como enviar solicitações para funções locais.

implante a função

Para implantar a função, execute o comando a seguir no diretório helloworld:

  gcloud functions deploy go-http-function \
    --gen2 \
    --runtime=go121 \
    --region=REGION \
    --source=. \
    --entry-point=HelloHTTP \
    --trigger-http \
    --allow-unauthenticated

Substitua REGION pelo nome da região do Google Cloud em que você quer implantar a função (por exemplo, us-west1).

A flag --allow-unauthenticated opcional permite que você acesse a função sem autenticação.

Testar a função implantada

  1. Depois que a função for implantada, observe a propriedade uri na saída do comando gcloud functions deploy ou recupere-a com o seguinte comando:

      gcloud functions describe go-http-function \
        --region=REGION
    

    Substitua REGION pelo nome da região do Google Cloud em que você implantou a função (por exemplo, us-west1).

  2. Acesse este URL no navegador. A função retorna uma mensagem "Hello World!".

    Encontre também esse URL no Console do Google Cloud. Acesse a página Visão geral do Cloud Run functions e clique no nome da função para abrir a página Detalhes da função. Abra a guia TRIGGER para ver o URL da sua função.

Conferir os registros da função

Conferir os registros com a ferramenta de linha de comando

É possível analisar os registros da função com a IU do Cloud Logging ou por meio da Google Cloud CLI.

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

    gcloud functions logs read \
      --gen2 \
      --limit=10 \
      --region=REGION \
      go-http-function

Substitua REGION pelo nome da região do Google Cloud em que você implantou a função (por exemplo, us-west1).

A saída será assim:

LEVEL: I
NAME: hellohttp
TIME_UTC: 2023-05-31 21:52:20.473
LOG:

LEVEL: I
NAME: hellohttp
TIME_UTC: 2023-05-31 21:52:20.370
LOG:

LEVEL: I
NAME: hellohttp
TIME_UTC: 2023-05-31 21:52:20.280
LOG: Default STARTUP TCP probe succeeded after 1 attempt for container "h-hello_h_t_t_p-1" on port 8080.

LEVEL: I
NAME: hellohttp
TIME_UTC: 2023-05-31 21:52:20.108
LOG:

Conferir os registros com o painel do Logging

Para ver os registros da função com o painel do Logging, abra a página de visão geral do Cloud Run functions e clique no nome da função na lista. Em seguida, clique na guia Registros.