Escribe funciones

En esta página, se proporciona una introducción para escribir funciones con el Framework de Functions.

Cuando escribas el código fuente de las funciones para Cloud Run, debes usar Functions Framework, una biblioteca de código abierto para escribir funciones de Cloud Run. Con Functions Framework, puedes escribir funciones ligeras que se ejecutan en Cloud Run y en otros entornos, incluida tu máquina de desarrollo local y los entornos basados en Knative.

Functions Framework te permite hacer lo siguiente:

  • Invoca una función en respuesta a una solicitud.
  • Desserializa automáticamente los eventos que se ajustan a la especificación de CloudEvents, una especificación estándar de la industria para describir los datos de eventos de manera común.
  • Inicia un servidor de desarrollo local para realizar pruebas rápidas.

Cómo escribir funciones con Functions Framework

Functions Framework proporciona una interfaz para compilar servicios modulares. Para usar el framework de funciones en tu código fuente, especifica lo siguiente:

Punto de entrada de la función

El código fuente debe definir un punto de entrada para la función, que es el código específico que se ejecuta cuando se invoca la función de Cloud Run. Especificas este punto de entrada cuando implementas tu función.

La forma en que defines el punto de entrada depende del entorno de ejecución del lenguaje que usas. Para algunos lenguajes, el punto de entrada es una función, mientras que, para otros, es una clase.

Tipo de firma

Cuando escribes el código fuente de una función con Functions Framework, debes especificar uno de los dos tipos de firma:

  • Funciones HTTP: Es una función que registra una función de controlador HTTP. Consulta Escribe funciones HTTP para obtener más información.
  • Funciones de CloudEvents (también llamadas funciones controladas por eventos): Es una función que registra una función del controlador de CloudEvents. Consulta Escribe funciones de CloudEvents para obtener más información.

Usa una función HTTP cuando necesites que tu función tenga un extremo de URL y responda a solicitudes HTTP, como para webhooks. Usa una función de CloudEvents cuando la función se deba activar directamente en respuesta a eventos dentro de tu proyecto deGoogle Cloud , como mensajes en un tema de Pub/Sub o cambios en un bucket de Cloud Storage.

Estructura de directorios del código fuente

Functions Framework es compatible con varios lenguajes de programación. El entorno de ejecución de lenguaje que elijas y el tipo de función que desees escribir determinarán cómo estructurar el código e implementar tu función.

Para que Cloud Run localice la definición de tu función, cada entorno de ejecución de lenguaje tiene requisitos para estructurar tu código fuente.

Node.js

A continuación, se muestra la estructura básica de directorios para las funciones de Node.js:

.
├── index.js
└── package.json

De forma predeterminada, Cloud Run intenta cargar el código fuente desde un archivo llamado index.js en la raíz del directorio de tu función. Para especificar un archivo de origen principal diferente, usa el campo main en el archivo package.json.

Tu archivo package.json también debe incluir Functions Framework para Node.js como una dependencia:

{
  "main": "index.js",
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}

El código de tu archivo principal debe definir el punto de entrada de la función y puede importar otros códigos y módulos de Node.js. El archivo principal también puede definir varios puntos de entrada de funciones que se pueden implementar por separado.

Consulta la descripción general del entorno de ejecución de Node.js y el Functions Framework para Node.js para obtener más detalles.

Python

A continuación, se muestra la estructura básica de directorios para las funciones de Python:

.
├── main.py
└── requirements.txt

Cloud Run carga el código fuente de un archivo llamado main.py en la raíz del directorio de tu función. Debes asignar el nombre main.py a tu archivo principal.

El archivo requirements.txt debe incluir Functions Framework para Python como una dependencia:

functions-framework==3.*

El código de tu archivo main.py debe definir el punto de entrada de la función y puede importar otro código y dependencias externas con normalidad. El archivo main.py también puede definir varios puntos de entrada de funciones que se pueden implementar por separado.

Consulta la descripción general del entorno de ejecución de Python y el framework de Functions para Python para obtener más detalles.

Go

La estructura básica de directorios para las funciones de Go es la siguiente:

.
├── myfunction.go
└── go.mod

Tu función debe estar en un paquete de Go en la raíz de tu proyecto. El paquete y sus archivos de origen pueden tener cualquier nombre, excepto que la función no puede estar en package main. Si necesitas un paquete main, por ejemplo, para realizar pruebas locales, puedes crear uno en un subdirectorio:

.
├── myfunction.go
├── go.mod
└── cmd/
  └── main.go

El archivo go.mod debe incluir Functions Framework para Go como una dependencia:

module example.com/my-module

require (
  github.com/GoogleCloudPlatform/functions-framework-go v1.5.2
)

El código de tu paquete raíz debe definir el punto de entrada de tu función y puede importar otro código de subpaquetes y dependencias con normalidad. El paquete también puede definir varios puntos de entrada de funciones que pueden implementarse por separado.

Consulta la descripción general del entorno de ejecución de Go y el framework de Functions para Go para obtener más detalles.

Java

La estructura de directorios básica de las funciones de Java es la siguiente:

.
├── pom.xml
└── src/
  └── main/
      └── java/
          └── MyFunction.java

Los archivos de origen de Java deben estar en el directorio src/main/java/ y pueden tener cualquier nombre. Si tus archivos de origen declaran un paquete, agrega un directorio adicional en src/main/java con el nombre del paquete:

.
├── pom.xml
└── src/
  └── main/
      └── java/
          └── mypackage/
              └── MyFunction.java

Recomendamos colocar pruebas asociadas en un subdirectorio src/test/java/.

El archivo pom.xml debe incluir Functions Framework para Java como una dependencia:

...
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.0.4</version>
    </dependency>
...

El código de tus archivos de origen debe definir el punto de entrada de la función y puede importar otro código y dependencias externas con normalidad. Los archivos de origen también pueden definir varios puntos de entrada de funciones que pueden implementarse por separado.

Consulta la descripción general del entorno de ejecución de Java y el framework de Functions para Java para obtener más detalles.

.NET

La estructura básica de directorios para las funciones de .NET es la siguiente:

.
├── MyFunction.cs
└── MyProject.csproj

Puedes estructurar los proyectos como lo harías con cualquier otro código fuente .NET. Los archivos de origen pueden tener cualquier nombre.

El archivo de tu proyecto debe incluir Functions Framework para .NET como una dependencia:

...
    <PackageReference Include="Google.Cloud.Functions.Hosting" Version="1.0.0" />
...

El código de tus archivos de origen debe definir el punto de entrada de la función y puede importar otro código y dependencias externas con normalidad. Los archivos de origen también pueden definir varios puntos de entrada de funciones que pueden implementarse por separado.

Consulta la descripción general del entorno de ejecución de.NET y el framework de Functions para .NET para obtener más detalles.

Ruby

La estructura de directorios básica de las funciones de Ruby es la siguiente:

.
├── app.rb
├── Gemfile
└── Gemfile.lock

Cloud Run carga el código fuente de un archivo llamado app.rb en la raíz del directorio de tu función. Tu archivo principal debe llamarse app.rb.

El archivo Gemfile debe incluir Functions Framework para Ruby como una dependencia:

source "https://rubygems.org"
gem "functions_framework", "~> 1.0"

El código de tu archivo app.rb debe definir el punto de entrada de la función y puede importar otro código y dependencias externas con normalidad. El archivo app.rb también puede definir varios puntos de entrada de funciones que se pueden implementar por separado.

Consulta la descripción general del entorno de ejecución de Ruby y el framework de Functions para Ruby para obtener más detalles.

PHP

La estructura básica de directorios para las funciones de PHP es la siguiente:

.
├── index.php
└── composer.json

Cloud Run carga el código fuente de un archivo llamado index.php en la raíz del directorio de tu función. Debes asignar el nombre index.php a tu archivo principal.

El archivo composer.json debe incluir Functions Framework para PHP como una dependencia:

{
  "require": {
    "google/cloud-functions-framework": "^1.1"
  }
}

El código de tu archivo index.php debe definir el punto de entrada de la función y puede importar otro código y dependencias externas con normalidad. El archivo index.php también puede definir varios puntos de entrada de funciones que se pueden implementar por separado.

Consulta la descripción general del entorno de ejecución de PHP y Functions Framework para PHP para obtener más detalles.

Si agrupas varias funciones en un solo proyecto, ten en cuenta que cada función puede terminar compartiendo el mismo conjunto de dependencias. Sin embargo, es posible que algunas de las funciones no necesiten todas las dependencias.

Siempre que sea posible, recomendamos dividir las bases de código multifunción grandes y colocar cada función en su propio directorio de nivel superior, como se muestra en los ejemplos anteriores, con sus propios archivos de configuración de origen y de proyecto. Este enfoque minimiza la cantidad de dependencias necesarias para una función específica, lo que, a su vez, reduce la cantidad de memoria que necesita tu función.

¿Qué sigue?