Crie e implemente uma função HTTP do Cloud Run com Java (1.ª geração)

Este guia explica o processo de escrita de uma função do Cloud Run usando o tempo de execução do Java. Existem dois tipos de funções do Cloud Run:

• Uma função HTTP, que invoca a partir de pedidos HTTP padrão.
• Uma função orientada por eventos, que usa para processar eventos da sua infraestrutura do Google Cloud, como mensagens num tópico Pub/Sub ou alterações num contentor do Cloud Storage.

O documento mostra como criar uma função HTTP simples e criá-la através do Maven ou do Gradle.

Saiba mais: para mais detalhes, leia acerca das funções HTTP e das funções orientadas por eventos.

Antes de começar

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.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Functions and Cloud Build APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Functions and Cloud Build APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

1. Instale e inicialize o SDK do Google Cloud.
2. Atualize e instale os componentes do gcloud:

   gcloud components update

Nota: precisa de uma linha de comandos? Pode usar o Google Cloud Shell. A Google Cloud Shell é um ambiente de linha de comandos que já inclui o SDK Cloud da Google, pelo que não precisa de o instalar. O SDK do Google Cloud também é pré-instalado em máquinas virtuais do Google Compute Engine.
3. Prepare o seu ambiente de desenvolvimento.

   Aceda ao guia de configuração do Java

Crie uma função

Esta secção descreve como criar uma função.

Maven

1. Crie um diretório no seu sistema local para o código da 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 ficheiro de origem.

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

3. Adicione os seguintes conteúdos ao ficheiro 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 produz a saudação "Olá mundo!"

Gradle

1. Crie um diretório no seu sistema local para o código da 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 ficheiro de origem.

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

3. Adicione os seguintes conteúdos ao ficheiro 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 produz a saudação "Olá mundo!"

Especifique dependências

O passo seguinte é configurar as dependências:

Maven

Mude o diretório para o diretório helloworld que criou acima e crie um ficheiro pom.xml:

 cd ~/helloworld
 touch pom.xml

Para gerir dependências através do Maven, especifique as dependências na secção <dependencies> no ficheiro pom.xml do seu projeto. Para este exercício, copie o seguinte conteúdo para o ficheiro 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 para ver um exemplo completo baseado no Maven.

Gradle

Mude o diretório para o diretório helloworld-gradle que criou acima e crie um ficheiro build.gradle:

 cd ~/helloworld-gradle
 touch build.gradle

Para gerir as dependências através do Gradle, especifique-as no ficheiro build.gradle do seu projeto. Para este exercício, copie o seguinte conteúdo para o ficheiro build.gradle. Tenha em atenção que este ficheiro build.gradle inclui uma tarefa personalizada para ajudar 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 para ver um exemplo completo baseado no Gradle.

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

Crie e teste localmente

Antes de implementar a função, pode criá-la e testá-la localmente:

Maven

Execute o seguinte comando para confirmar que a função é criada:

mvn compile

Outra opção é usar o comando mvn package para compilar o código Java, executar quaisquer testes e agrupar o código num ficheiro JAR no diretório de destino. Pode saber mais sobre o ciclo de vida de compilação do Maven aqui.

Para testar a função, execute o seguinte comando:

mvn function:run

Gradle

Execute o seguinte comando para confirmar que a função é criada:

gradle build

Para testar a função, execute o seguinte comando:

gradle runFunction -Prun.functionTarget=functions.HelloWorld

Se o teste for concluído com êxito, é apresentado o URL que pode visitar no seu navegador de Internet para ver a função em ação: http://localhost:8080/. Deverá ver uma mensagem Hello World!.

Em alternativa, pode enviar pedidos para esta função através de curl a partir de outra janela de terminal:

curl localhost:8080
# Output: Hello World!

Implemente a função

Maven

Para implementar a função com um acionador HTTP, execute o seguinte comando no diretório helloworld:

gcloud functions deploy my-first-function --no-gen2 --entry-point functions.HelloWorld --runtime java17 --trigger-http --memory 512MB --allow-unauthenticated

onde my-first-function é o nome registado pelo qual a sua função vai ser identificada na Google Cloud consola e --entry-point especifica o nome da classe totalmente qualificado (FQN) da sua função.

Gradle

Para implementar a função com um acionador HTTP, execute o seguinte comando no diretório helloworld-gradle:

gcloud functions deploy my-first-function --no-gen2 --entry-point functions.HelloWorld --runtime java17 --trigger-http --memory 512MB --allow-unauthenticated

onde my-first-function é o nome registado pelo qual a sua função vai ser identificada na Google Cloud consola e --entry-point especifica o nome da classe totalmente qualificado (FQN) da sua função.

Saiba mais: para mais detalhes, leia sobre a implementação de funções do Cloud Run.

Teste a função implementada

1. Quando a implementação da função terminar, tome nota da propriedade httpsTrigger.url ou encontre-a através do seguinte comando:

   gcloud functions describe my-first-function

   Deve ter este aspeto:

   https://GCP_REGION-PROJECT_ID.cloudfunctions.net/my-first-function

2. Visite este URL no seu navegador. Deverá ver uma mensagem Hello World!.

Nota: também pode encontrar este URL na Google Cloud consola. Aceda à página Vista geral das funções do Cloud Run e clique no nome da sua função para abrir a respetiva página Detalhes da função. Abra o separador TRIGGER para ver o URL da sua função.

Ver registos

Os registos das funções do Cloud Run são visíveis através da CLI gcloud e na IU do Cloud Logging.

Use a ferramenta de linha de comandos

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

gcloud functions logs read my-first-function

O resultado deve ser semelhante ao seguinte:

LEVEL  NAME               EXECUTION_ID  TIME_UTC                 LOG
D      my-first-function  k2bqgroszo4u  2020-07-24 18:18:01.791  Function execution started
D      my-first-function  k2bqgroszo4u  2020-07-24 18:18:01.958  Function execution took 168 ms, finished with status code: 200
...

Nota: normalmente, existe um ligeiro atraso entre o momento em que as entradas do registo são criadas e o momento em que são apresentadas no Cloud Logging.

Use o painel de controlo de registo

Também pode ver os registos das funções do Cloud Run a partir da Google Cloud consola.

Saiba mais: para mais detalhes, leia sobre como escrever, ver e responder a registos.