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

Este guia explica o processo de criação de uma função do Cloud Run usando o ambiente de execução Java. 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.

O documento mostra como criar uma função HTTP simples e criá-la usando Maven (em inglês) ou Gradle (em inglês).

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. Make sure that billing is enabled for your Google Cloud project.

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

    Enable the APIs

    5.

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

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

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

    Enable the APIs

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

    Acessar o guia de configuração do Java

Criar a função

Nesta seção, descrevemos como criar funções.

Maven

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

    Linux ou Mac OS X:

     mkdir ~/helloworld
 cd ~/helloworld

    Windows:

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

  2. Crie a estrutura do projeto para conter o diretório de origem e o arquivo de origem.

    mkdir -p ~/helloworld/src/main/java/functions
touch ~/helloworld/src/main/java/functions/HelloWorld.java

  3. Adicione o seguinte conteúdo ao arquivo HelloWorld.java:

    
package functions;

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import java.io.BufferedWriter;
import java.io.IOException;

public class HelloWorld implements HttpFunction {
  // Simple function to return "Hello World"
  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    BufferedWriter writer = response.getWriter();
    writer.write("Hello World!");
  }
}

    Esta função de exemplo gera a saudação "Hello World!"

Gradle

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

    Linux ou Mac OS X:

     mkdir ~/helloworld-gradle
 cd ~/helloworld-gradle

    Windows:

     mkdir %HOMEPATH%\helloworld-gradle
 cd %HOMEPATH%\helloworld-gradle

  2. Crie a estrutura do projeto para conter o diretório de origem e o arquivo de origem.

     mkdir -p src/main/java/functions
 touch src/main/java/functions/HelloWorld.java

  3. Adicione o seguinte conteúdo ao arquivo HelloWorld.java:

    
package functions;

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import java.io.BufferedWriter;
import java.io.IOException;

public class HelloWorld implements HttpFunction {
  // Simple function to return "Hello World"
  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    BufferedWriter writer = response.getWriter();
    writer.write("Hello World!");
  }
}

    Esta função de exemplo gera a saudação "Hello World!"

Especificar as dependências

A próxima etapa é configurar as dependências:

Maven

Altere o diretório para o diretório helloworld criado acima e crie um arquivo pom.xml:

 cd ~/helloworld
 touch pom.xml

Para gerenciar dependências usando o Maven, especifique as dependências na seção <dependencies> dentro do arquivo pom.xml (em inglês) do projeto. Para este exercício, copie o conteúdo a seguir no arquivo pom.xml.

<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example.functions</groupId>
  <artifactId>functions-hello-world</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <properties>
    <maven.compiler.target>11</maven.compiler.target>
    <maven.compiler.source>11</maven.compiler.source>
  </properties>

  <dependencies>
    <!-- Required for Function primitives -->
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.1.0</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <!--
          Google Cloud Functions Framework Maven plugin

          This plugin allows you to run Cloud Functions Java code
          locally. Use the following terminal command to run a
          given function locally:

          mvn function:run -Drun.functionTarget=your.package.yourFunction
        -->
        <groupId>com.google.cloud.functions</groupId>
        <artifactId>function-maven-plugin</artifactId>
        <version>0.11.0</version>
        <configuration>
          <functionTarget>functions.HelloWorld</functionTarget>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Consulte helloworld (em inglês) para uma amostra completa com base no Maven.

Gradle

Altere o diretório para o diretório helloworld-gradle criado acima e crie um arquivo build.gradle:

 cd ~/helloworld-gradle
 touch build.gradle

Para gerenciar dependências usando o Gradle, especifique as dependências no arquivo build.gradle (em inglês) do projeto. Para este exercício, copie o conteúdo a seguir no arquivo build.gradle. Este arquivo build.gradle inclui uma tarefa personalizada para ajudar você a executar funções localmente.

apply plugin: 'java'

repositories {
  jcenter()
  mavenCentral()
}
configurations {
    invoker
}

dependencies {
  // Every function needs this dependency to get the Functions Framework API.
  compileOnly 'com.google.cloud.functions:functions-framework-api:1.1.0'

  // To run function locally using Functions Framework's local invoker
  invoker 'com.google.cloud.functions.invoker:java-function-invoker:1.3.1'

  // These dependencies are only used by the tests.
  testImplementation 'com.google.cloud.functions:functions-framework-api:1.1.0'
  testImplementation 'junit:junit:4.13.2'
  testImplementation 'com.google.truth:truth:1.4.0'
  testImplementation 'org.mockito:mockito-core:5.10.0'

}

// Register a "runFunction" task to run the function locally
tasks.register("runFunction", JavaExec) {
  main = 'com.google.cloud.functions.invoker.runner.Invoker'
  classpath(configurations.invoker)
  inputs.files(configurations.runtimeClasspath, sourceSets.main.output)
  args(
    '--target', project.findProperty('run.functionTarget') ?: '',
    '--port', project.findProperty('run.port') ?: 8080
  )
  doFirst {
    args('--classpath', files(configurations.runtimeClasspath, sourceSets.main.output).asPath)
  }
}

Consulte helloworld-gradle (em inglês) para ver uma amostra completa com base no Gradle.

.

Criar e testar a função localmente

Antes de implantar a função, é possível criá-la e testá-la localmente:

Maven

  1. Execute o seguinte comando para confirmar se a função foi criada:

    mvn compile

    Outra opção é usar o comando mvn package para compilar o código Java, executar todos os testes e empacotar o código em um arquivo JAR no diretório de destino. Saiba mais sobre o ciclo de vida da versão do Maven (em inglês).

  2. Inicie a função com o seguinte comando:

    mvn function:run

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

Gradle

  1. Execute o seguinte comando para confirmar se a função foi criada:

    gradle build

  2. Inicie a função com o seguinte comando:

    gradle runFunction -Prun.functionTarget=functions.HelloWorld

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

Implantar a função

Para implantar a função, execute o seguinte comando no diretório helloworld (se você estiver usando maven) ou no diretório helloworld-gradle (para Gradle):

  gcloud functions deploy java-http-function \
    --gen2 \
    --entry-point=functions.HelloWorld \
    --runtime=java17 \
    --region=REGION \
    --source=. \
    --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.

java-http-function é o nome registrado pelo qual sua função é identificada no console do Google Cloud, e --entry-point especifica o nome de classe totalmente qualificado da função (FQN).

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 java-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!".

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 \
      java-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: my-first-function
TIME_UTC: 2023-05-29 23:09:57.708
LOG:

LEVEL: I
NAME: my-first-function
TIME_UTC: 2023-05-29 23:05:53.257
LOG: Default STARTUP TCP probe succeeded after 1 attempt for container "my--first--function-1" on port 8080.

LEVEL:
NAME: my-first-function
TIME_UTC: 2023-05-29 23:05:53.248
LOG: 2023-05-29 23:05:53.248:INFO:oejs.Server:main: Started @892ms

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.