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

Observação: este conteúdo se aplica apenas às funções do Cloud Run, anteriormente chamadas de Cloud Functions (2ª geração).

Para acessar a versão de 1ª geração deste documento, consulte Criar e implantar funções do Cloud Run em HTTP com Java (1ª geração).

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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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. Instale e inicialize o Google Cloud SDK.
   Observação: precisa de um prompt de comando? É possível usar o Cloud Shell. O Cloud Shell é um ambiente de linha de comando que já inclui a CLI do Google Cloud. Portanto, não é necessário instalá-lo. A Google Cloud CLI também vem pré-instalado em máquinas virtuais do Google Compute Engine.
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.

Saiba mais: para mais detalhes, leia sobre como especificar dependências

.

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=java21 \
    --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).

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

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

   Observação: 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 \
      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

Observação: pode haver um pequeno atraso antes de as entradas de registro aparecerem no Cloud Logging.

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.

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