Criar e implantar uma função HTTP do Cloud Run usando 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 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 documento mostra como criar uma função HTTP simples e criá-la usando Maven (em inglês) ou Gradle (em inglês).

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 conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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 role (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 role (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 Google Cloud SDK.
2. Atualize e instale os componentes gcloud:

   gcloud components update

Observação: precisa de um prompt de comando? Use o Google Cloud Shell. O Google Cloud Shell é um ambiente de linha de comando que já inclui o SDK do Google Cloud. Dessa maneira, você não precisa instalá-lo. O SDK do Google Cloud também vem pré-instalado em máquinas virtuais do Google Compute Engine.
3. Prepare seu ambiente de desenvolvimento.

   Acessar o guia de configuração do Java

crie uma 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 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!"

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 localmente

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

Maven

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

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

mvn function:run

Gradle

Execute o seguinte comando para confirmar se a função foi 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, ele exibirá o URL que pode ser acessado no navegador da Web para ver a função em ação: http://localhost:8080/. Você verá uma mensagem Hello World!.

Como alternativa, envie solicitações para essa função usando curl de outra janela de terminal:

curl localhost:8080
# Output: Hello World!

Implantar a função

Maven

Para implantar a função com um gatilho 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

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

Gradle

Para implantar a função com um gatilho 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

em que my-first-function é o nome registrado pelo qual sua função será 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 de implantaçã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 my-first-function

   A aparência será semelhante a esta:

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

2. Visite este URL no navegador. Você verá 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 GATILHO para ver o URL da sua função.

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 ferramenta gcloud CLI, use o comando logs read, seguido pelo nome da função:

gcloud functions logs read my-first-function

A saída será semelhante a esta:

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

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 console doGoogle Cloud .

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