Crear y desplegar una función de Cloud Run activada por HTTP con Java (1.ª gen.)

En esta guía se explica cómo escribir una función de Cloud Run con el entorno de ejecución de Java. Hay dos tipos de funciones de Cloud Run:

• Una función HTTP, que se invoca desde solicitudes HTTP estándar.
• Una función basada en eventos que se usa para gestionar eventos de tu infraestructura de Cloud, como mensajes de un tema de Pub/Sub o cambios en un segmento de Cloud Storage.

En el documento se muestra cómo crear una función HTTP sencilla y compilarla con Maven o Gradle.

Más información: para obtener más detalles, consulta las funciones HTTP y las funciones basadas en eventos.

Antes de empezar

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. Instala e inicializa el SDK de Google Cloud.
2. Actualiza e instala los componentes de gcloud:

   gcloud components update

Nota: ¿Necesitas un símbolo del sistema? Puedes usar Google Cloud Shell. Google Cloud Shell es un entorno de línea de comandos que ya incluye el SDK de Google Cloud, por lo que no necesitas instalarlo. El SDK de Google Cloud también está preinstalado en las máquinas virtuales de Google Compute Engine.
3. Prepara tu entorno de desarrollo.

   Ir a la guía de configuración de Java

Crear una función

En esta sección se describe cómo crear una función.

Maven

1. Crea un directorio en tu sistema local para el código de la función:

   Linux o Mac OS X:

    mkdir ~/helloworld
    cd ~/helloworld
   

   Windows:

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

2. Crea la estructura del proyecto para que contenga el directorio de origen y el archivo de origen.

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

3. Añade el siguiente contenido al archivo 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 función de ejemplo muestra el saludo "Hello World!".

Gradle

1. Crea un directorio en tu sistema local para el código de la función:

   Linux o Mac OS X:

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

   Windows:

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

2. Crea la estructura del proyecto para que contenga el directorio de origen y el archivo de origen.

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

3. Añade el siguiente contenido al archivo 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 función de ejemplo muestra el saludo "Hello World!".

Especificar dependencias

El siguiente paso es configurar las dependencias:

Maven

Cambia el directorio al directorio helloworld que has creado anteriormente y crea un archivo pom.xml:

 cd ~/helloworld
 touch pom.xml

Para gestionar las dependencias con Maven, especifícalas en la sección <dependencies> del archivo pom.xml de tu proyecto. Para este ejercicio, copia el siguiente contenido en tu archivo 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>

Consulta helloworld para ver un ejemplo completo basado en Maven.

Gradle

Cambia al directorio helloworld-gradle que has creado anteriormente y crea un archivo build.gradle:

 cd ~/helloworld-gradle
 touch build.gradle

Para gestionar las dependencias con Gradle, especifícalas en el archivo build.gradle de tu proyecto. Para este ejercicio, copia el siguiente contenido en tu archivo build.gradle. Ten en cuenta que este archivo build.gradle incluye una tarea personalizada para ayudarte a ejecutar funciones 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)
  }
}

Consulta helloworld-gradle para ver un ejemplo completo basado en Gradle.

Más información: para obtener más detalles, consulta cómo especificar dependencias.

Compilar y probar de forma local

Antes de desplegar la función, puedes compilarla y probarla de forma local:

Maven

Ejecuta el siguiente comando para confirmar que tu función se compila:

mvn compile

Otra opción es usar el comando mvn package para compilar el código Java, ejecutar las pruebas y empaquetar el código en un archivo JAR en el directorio de destino. Puedes consultar más información sobre el ciclo de vida de compilación de Maven aquí.

Para probar la función, ejecuta el siguiente comando:

mvn function:run

Gradle

Ejecuta el siguiente comando para confirmar que tu función se compila:

gradle build

Para probar la función, ejecuta el siguiente comando:

gradle runFunction -Prun.functionTarget=functions.HelloWorld

Si la prueba se completa correctamente, se muestra la URL que puedes visitar en tu navegador web para ver la función en acción: http://localhost:8080/. Debería aparecer un mensaje Hello World!.

También puedes enviar solicitudes a esta función mediante curl desde otra ventana de terminal:

curl localhost:8080
# Output: Hello World!

Desplegar la función

Maven

Para desplegar la función con un activador HTTP, ejecuta el siguiente comando en el directorio helloworld:

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

donde my-first-function es el nombre registrado por el que se identificará tu función en la consola Google Cloud y --entry-point especifica el nombre de clase totalmente cualificado (FQN) de tu función.

Gradle

Para desplegar la función con un activador HTTP, ejecuta el siguiente comando en el directorio helloworld-gradle:

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

donde my-first-function es el nombre registrado por el que se identificará tu función en la consola Google Cloud y --entry-point especifica el nombre de clase totalmente cualificado (FQN) de tu función.

Más información: para obtener más detalles, consulta cómo desplegar funciones de Cloud Run.

Probar la función implementada

1. Cuando la función termine de implementarse, anota la propiedad httpsTrigger.url o búscala con el siguiente comando:

   gcloud functions describe my-first-function

   Debería tener este aspecto:

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

2. Visita esta URL en tu navegador. Debería aparecer un mensaje Hello World!.

Nota: También puedes encontrar esta URL en la consola de Google Cloud . Ve a la página de descripción general de Cloud Run Functions y haz clic en el nombre de tu función para abrir su página Detalles de la función. Abre la pestaña ACTIVADOR para ver la URL de tu función.

Ver registros

Los registros de las funciones de Cloud Run se pueden ver con la CLI de Google Cloud y en la interfaz de usuario de Cloud Logging.

Usar la herramienta de línea de comandos

Para ver los registros de tu función con gcloud CLI, usa el comando logs read, seguido del nombre de la función:

gcloud functions logs read my-first-function

La salida debería ser similar a la siguiente:

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, hay un pequeño retraso entre el momento en que se crean las entradas de registro y el momento en que aparecen en Cloud Logging.

Usar el panel de control de Logging

También puedes ver los registros de las funciones de Cloud Run desde la Google Cloud consola.

Más información: para obtener más detalles, consulta cómo escribir, ver y responder registros.