Comience: escriba, pruebe e implemente sus primeras funciones

Para comenzar con Cloud Functions, intente seguir este tutorial, que comienza con las tareas de configuración requeridas y avanza mediante la creación, prueba e implementación de dos funciones relacionadas:

• Una función de "agregar mensaje" que expone una URL que acepta un valor de texto y lo escribe en Cloud Firestore.
• Una función de "poner en mayúsculas" que se activa al escribir en Cloud Firestore y transforma el texto a mayúsculas.

Aquí está el código de muestra completo que contiene las funciones:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await getFirestore()
      .collection("messages")
      .add({original: original});
  // Send back a message that we've successfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

// Listens for new messages added to /messages/:documentId/original
// and saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()


@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")


@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

Acerca de este tutorial

Elegimos Cloud Firestore y las funciones activadas por HTTP para este ejemplo en parte porque estos activadores en segundo plano se pueden probar minuciosamente a través de Firebase Local Emulator Suite . Este conjunto de herramientas también admite activadores invocables de bases de datos en tiempo real, almacenamiento en la nube, PubSub, autenticación y HTTP. Otros tipos de activadores en segundo plano, como los activadores de Remote Config y TestLab, se pueden probar de forma interactiva utilizando conjuntos de herramientas que no se describen en esta página.

Las siguientes secciones de este tutorial detallan los pasos necesarios para compilar, probar e implementar el ejemplo.

Crear un proyecto de Firebase

1. En Firebase console , haz clic en Agregar proyecto .

   • Para agregar recursos de Firebase a un proyecto de Google Cloud existente , ingrese el nombre del proyecto o selecciónelo en el menú desplegable.

   • Para crear un nuevo proyecto, ingrese el nombre del proyecto deseado. Opcionalmente, también puede editar el ID del proyecto que se muestra debajo del nombre del proyecto.

2. Si se te solicita, revisa y acepta los términos de Firebase .

3. Haga clic en Continuar .

4. (Opcional) Configure Google Analytics para su proyecto, lo que le permitirá tener una experiencia óptima al utilizar cualquiera de los siguientes productos de Firebase:

   Crashlytics de base de fuego Mensajería en la nube de Firebase

   Mensajería en la aplicación de Firebase Configuración remota de Firebase

   Personalización de configuración remota Pruebas A/B de Firebase

   Seleccione una cuenta de Google Analytics existente o cree una cuenta nueva.

   Si crea una cuenta nueva, seleccione la ubicación de sus informes de Analytics y luego acepte la configuración de intercambio de datos y los términos de Google Analytics para su proyecto.

5. Haz clic en Crear proyecto (o Agregar Firebase , si estás usando un proyecto de Google Cloud existente).

Firebase aprovisiona automáticamente recursos para tu proyecto de Firebase. Cuando se complete el proceso, accederás a la página de descripción general de tu proyecto de Firebase en Firebase console.

Configura tu entorno y Firebase CLI

Inicializa tu proyecto

Cuando inicializas el SDK de Firebase para Cloud Functions, creas un proyecto vacío que contiene dependencias y un código de muestra mínimo. Si está utilizando Node.js, puede elegir TypeScript o JavaScript para componer funciones. Para los fines de este tutorial, también necesitarás inicializar Cloud Firestore.

Para inicializar su proyecto:

1. Ejecute firebase login para iniciar sesión a través del navegador y autenticar Firebase CLI.
2. Vaya al directorio de su proyecto de Firebase.
3. Ejecute firebase init firestore . Para este tutorial, puede aceptar los valores predeterminados cuando se le soliciten reglas y archivos de índice de Firestore. Si aún no ha utilizado Cloud Firestore en este proyecto, también deberá seleccionar un modo de inicio y una ubicación para Firestore como se describe en Introducción a Cloud Firestore .
4. Ejecute firebase init functions . La CLI le solicita que elija una base de código existente o inicialice y nombre una nueva. Cuando recién estás comenzando, una única base de código en la ubicación predeterminada es adecuada; Más adelante, a medida que se expanda su implementación, es posible que desee organizar funciones en bases de código .

5. La CLI le ofrece estas opciones para la compatibilidad con idiomas:

   • javascript
   • Mecanografiado
   • Pitón

   Para este tutorial, seleccione JavaScript o Python . Para la creación en TypeScript, consulte Escribir funciones con TypeScript .

6. La CLI le ofrece la opción de instalar dependencias. Es seguro rechazarlo si desea administrar las dependencias de otra manera.

Una vez que estos comandos se completen exitosamente, la estructura de su proyecto se verá así:

myproject
+- .firebaserc    # Hidden file that helps you quickly switch between
|                 # projects with `firebase use`
|
+- firebase.json  # Describes properties for your project
|
+- functions/     # Directory containing all your functions code
      |
      +- .eslintrc.json  # Optional file containing rules for JavaScript linting.
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- index.js      # Main source file for your Cloud Functions code
      |
      +- node_modules/ # Directory where your dependencies (declared in
                        # package.json) are installed

myproject
+- .firebaserc    # Hidden file that helps you quickly switch between
|                 # projects with `firebase use`
|
+- firebase.json  # Describes properties for your project
|
+- functions/     # Directory containing all your functions code
      |
      +- main.py      # Main source file for your Cloud Functions code
      |
      +- requirements.txt  #  List of the project's modules and packages 
      |
      +- venv/ # Directory where your dependencies are installed

Importe los módulos necesarios e inicialice una aplicación

Una vez que haya completado las tareas de configuración, puede abrir el directorio fuente y comenzar a agregar código como se describe en las siguientes secciones. Para este ejemplo, su proyecto debe importar los módulos Cloud Functions y Admin SDK. Agregue líneas como las siguientes a su archivo fuente:

// The Cloud Functions for Firebase SDK to create Cloud Functions and triggers.
const {logger} = require("firebase-functions");
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

// The Firebase Admin SDK to access Firestore.
const {initializeApp} = require("firebase-admin/app");
const {getFirestore} = require("firebase-admin/firestore");

initializeApp();
index.js

# The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
from firebase_functions import firestore_fn, https_fn

# The Firebase Admin SDK to access Cloud Firestore.
from firebase_admin import initialize_app, firestore
import google.cloud.firestore

app = initialize_app()
main.py

Estas líneas cargan los módulos necesarios e inicializan una instancia de aplicación admin desde la cual se pueden realizar cambios en Cloud Firestore. Dondequiera que esté disponible la compatibilidad con Admin SDK , como lo está para FCM, Autenticación y Firebase Realtime Database, proporciona una manera poderosa de integrar Firebase usando Cloud Functions.

Firebase CLI instala automáticamente los módulos Firebase Admin SDK y Firebase SDK para Cloud Functions cuando inicializas tu proyecto. Para obtener más información sobre cómo agregar bibliotecas de terceros a su proyecto, consulte Manejar dependencias .

Agregue la función "agregar mensaje"

Para la función "agregar mensaje", agregue estas líneas a su archivo fuente:

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addmessage = onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await getFirestore()
      .collection("messages")
      .add({original: original});
  // Send back a message that we've successfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});
index.js

@https_fn.on_request()
def addmessage(req: https_fn.Request) -> https_fn.Response:
    """Take the text parameter passed to this HTTP endpoint and insert it into
    a new document in the messages collection."""
    # Grab the text parameter.
    original = req.args.get("text")
    if original is None:
        return https_fn.Response("No text parameter provided", status=400)

    firestore_client: google.cloud.firestore.Client = firestore.client()

    # Push the new message into Cloud Firestore using the Firebase Admin SDK.
    _, doc_ref = firestore_client.collection("messages").add({"original": original})

    # Send back a message that we've successfully written the message
    return https_fn.Response(f"Message with ID {doc_ref.id} added.")
main.py

La función "agregar mensaje" es un punto final HTTP. Cualquier solicitud al punto final da como resultado objetos de solicitud y respuesta pasados ​​al controlador de solicitudes de su plataforma ( onRequest() o on_request ).

Las funciones HTTP son síncronas (similares a las funciones invocables ), por lo que debes enviar una respuesta lo más rápido posible y posponer el trabajo usando Cloud Firestore. La función HTTP "agregar mensaje" pasa un valor de texto al punto final HTTP y lo inserta en la base de datos en la ruta /messages/:documentId/original .

Agregue la función "poner mayúsculas"

Para la función "poner mayúsculas", agregue estas líneas a su archivo fuente:

// Listens for new messages added to /messages/:documentId/original
// and saves an uppercased version of the message
// to /messages/:documentId/uppercase
exports.makeuppercase = onDocumentCreated("/messages/{documentId}", (event) => {
  // Grab the current value of what was written to Firestore.
  const original = event.data.data().original;

  // Access the parameter `{documentId}` with `event.params`
  logger.log("Uppercasing", event.params.documentId, original);

  const uppercase = original.toUpperCase();

  // You must return a Promise when performing
  // asynchronous tasks inside a function
  // such as writing to Firestore.
  // Setting an 'uppercase' field in Firestore document returns a Promise.
  return event.data.ref.set({uppercase}, {merge: true});
});
index.js

@firestore_fn.on_document_created(document="messages/{pushId}")
def makeuppercase(event: firestore_fn.Event[firestore_fn.DocumentSnapshot | None]) -> None:
    """Listens for new documents to be added to /messages. If the document has
    an "original" field, creates an "uppercase" field containg the contents of
    "original" in upper case."""

    # Get the value of "original" if it exists.
    if event.data is None:
        return
    try:
        original = event.data.get("original")
    except KeyError:
        # No "original" field, so do nothing.
        return

    # Set the "uppercase" field.
    print(f"Uppercasing {event.params['pushId']}: {original}")
    upper = original.upper()
    event.data.reference.update({"uppercase": upper})
main.py

La función "poner en mayúsculas" se ejecuta cuando se escribe en Cloud Firestore, definiendo el documento que se escuchará. Por motivos de rendimiento, debes ser lo más específico posible.

Las llaves (por ejemplo, {documentId} rodean los "parámetros", comodines que exponen sus datos coincidentes en la devolución de llamada. Cloud Firestore activa la devolución de llamada cada vez que se agregan nuevos mensajes.

En Node.js, las funciones controladas por eventos, como los eventos de Cloud Firestore, son asincrónicas. La función de devolución de llamada debe devolver un null , un objeto o una promesa . Si no devuelve nada, la función expira, lo que indica un error y se vuelve a intentar. Consulte Sincronización, Asíncrono y Promesas .

Emula la ejecución de tus funciones.

Firebase Local Emulator Suite le permite crear y probar aplicaciones en su máquina local en lugar de implementarlas en un proyecto de Firebase. Se recomienda encarecidamente realizar pruebas locales durante el desarrollo, en parte porque reduce el riesgo de errores de codificación que podrían generar costos en un entorno de producción (por ejemplo, un bucle infinito).

Para emular sus funciones:

1. Ejecute firebase emulators:start y verifique el resultado de la URL de la interfaz de usuario de Emulator Suite. El valor predeterminado es localhost:4000 , pero puede estar alojado en un puerto diferente de su máquina. Ingrese esa URL en su navegador para abrir la interfaz de usuario de Emulator Suite.

2. Verifique la salida del comando firebase emulators:start para ver la URL de la función HTTP. Será similar a http://localhost:5001/MY_PROJECT/us-central1/addMessage , excepto que:

   1. MY_PROJECT será reemplazado por el ID de su proyecto.
   2. El puerto puede ser diferente en su máquina local.

3. Agregue la cadena de consulta ?text=uppercaseme al final de la URL de la función. Esto debería verse así: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme . Opcionalmente, puede cambiar el mensaje "mayúsculas" a un mensaje personalizado.

4. Cree un mensaje nuevo abriendo la URL en una nueva pestaña de su navegador.

5. Vea los efectos de las funciones en la interfaz de usuario de Emulator Suite:

   1. En la pestaña Registros , debería ver nuevos registros que indiquen que sus funciones HTTP se ejecutaron correctamente:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

   2. En la pestaña Firestore , debería ver un documento que contiene su mensaje original, así como la versión en mayúsculas de su mensaje (si originalmente estaba en "mayúsculas", verá "MAYÚSCULAS").

Implementar funciones en un entorno de producción.

Una vez que sus funciones funcionen como desea en el emulador, puede proceder a implementarlas, probarlas y ejecutarlas en el entorno de producción. Tenga en cuenta que para implementarlo en producción, su proyecto debe estar en el plan de precios de Blaze . Consulte los precios de Cloud Functions .

Para completar el tutorial, implemente sus funciones y luego ejecútelas.

1. Ejecute este comando para implementar sus funciones:

    firebase deploy --only functions
    

   Después de ejecutar este comando, Firebase CLI genera la URL para cualquier punto final de función HTTP. En tu terminal, deberías ver una línea como la siguiente:

   Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
   

   La URL contiene el ID de su proyecto, así como una región para la función HTTP. Aunque no necesita preocuparse por eso ahora, algunas funciones HTTP de producción deben especificar una ubicación para minimizar la latencia de la red.

   Si encuentra errores de acceso como "No se puede autorizar el acceso al proyecto", intente verificar el alias de su proyecto .

2. Usando la URL generada por la CLI, agregue un parámetro de consulta de texto y ábralo en un navegador:

   https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
   

   La función se ejecuta y redirige el navegador a la consola Firebase en la ubicación de la base de datos donde se almacena la cadena de texto. Este evento de escritura activa la función "poner en mayúsculas", que escribe una versión en mayúsculas de la cadena.

Después de implementar y ejecutar funciones, puede ver los registros en la consola de Google Cloud . Si necesita eliminar funciones en desarrollo o producción, use Firebase CLI.

En producción, es posible que desee optimizar el rendimiento de la función y controlar los costos estableciendo un número mínimo y máximo de instancias para ejecutar. Consulte Controlar el comportamiento de escalado para obtener más información sobre estas opciones de tiempo de ejecución.

Próximos pasos

En esta documentación, puede obtener más información sobre cómo administrar funciones para Cloud Functions y cómo manejar todos los tipos de eventos admitidos por Cloud Functions.

Para obtener más información sobre Cloud Functions, también puede hacer lo siguiente:

• Lea acerca de los casos de uso de Cloud Functions .
• Pruebe el codelab de Cloud Functions .
• Revisar y ejecutar ejemplos de código en GitHub