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.

Elegimos Cloud Firestore y las funciones de JavaScript 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 Realtime Database, PubSub, Auth y HTTP. Otros tipos de activadores en segundo plano, como los activadores de Remote Config, TestLab y Analytics, 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. Si prefiere simplemente ejecutar el código e inspeccionarlo, vaya a Revisar el código de muestra completo .

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:

    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.

Configurar Node.js y Firebase CLI

Necesitará un entorno Node.js para escribir funciones y Firebase CLI para implementar funciones en el tiempo de ejecución de Cloud Functions. Para instalar Node.js y npm , se recomienda Node Version Manager .

Una vez que tenga Node.js y npm instalados, instale Firebase CLI mediante su método preferido. Para instalar la CLI a través de npm, use:

npm install -g firebase-tools

Esto instala el comando firebase disponible globalmente. Si el comando falla, es posible que deba cambiar los permisos de npm . Para actualizar a la última versión de firebase-tools , vuelva a ejecutar el mismo comando.

Inicializa tu proyecto

Cuando inicializas Firebase SDK para Cloud Functions, creas un proyecto vacío que contiene dependencias y un código de muestra mínimo, y eliges 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 dos opciones para la compatibilidad con idiomas:

    Para este tutorial, seleccione JavaScript .

  6. La CLI le ofrece la opción de instalar dependencias con npm. Es seguro rechazarlo si desea administrar las dependencias de otra manera, aunque si lo rechaza deberá ejecutar npm install antes de emular o implementar sus funciones.

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

El archivo package.json creado durante la inicialización contiene una clave importante: "engines": {"node": "16"} . Esto especifica su versión de Node.js para escribir e implementar funciones. Puede seleccionar otras versiones compatibles .

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 mediante declaraciones require de Node. Agregue líneas como las siguientes a su archivo index.js :

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const admin = require("firebase-admin");
admin.initializeApp();
index.js

Estas líneas cargan los módulos firebase-functions y firebase-admin 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 y Firebase SDK para Cloud Functions Node cuando inicializas tu proyecto. Para agregar bibliotecas de terceros a su proyecto, puede modificar package.json y ejecutar npm install . Para obtener más información, consulte Manejar dependencias .

Agregue la función addMessage()

Para la función addMessage() , agregue estas líneas a index.js :

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.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 admin
    .firestore()
    .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

La función addMessage() es un punto final HTTP. Cualquier solicitud al punto final da como resultado objetos de solicitud y respuesta de estilo ExpressJS pasados ​​a la devolución de llamada onRequest() .

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 addMessage() 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 makeUppercase()

Para la función makeUppercase() , agregue estas líneas a index.js :

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

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

    const uppercase = original.toUpperCase();

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

La función makeUppercase() se ejecuta cuando se escribe en Cloud Firestore. La función ref.set define el documento a 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 onCreate() cada vez que se agregan nuevos mensajes.

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 el resultado del comando firebase emulators:start para ver la URL de la función HTTP addMessage() . 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 se ejecutaron las funciones addMessage() y makeUppercase() :

      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 implementar en el entorno de ejecución Node.js 14 recomendado, su proyecto debe estar en el plan de precios Blaze . Consulte los precios de Cloud Functions .

Para completar el tutorial, implemente sus funciones y luego ejecute addMessage() para activar makeUppercase() .

  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. Utilizando la URL addMessage() 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 makeUppercase() , 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.

Revisar el código de muestra completo

Aquí están las functions/index.js completadas que contienen las funciones addMessage() y makeUppercase() . Estas funciones te permiten pasar un parámetro a un extremo HTTP que escribe un valor en Cloud Firestore y luego lo transforma poniendo en mayúsculas todos los caracteres de la cadena.

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

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

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.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 admin
    .firestore()
    .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 creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

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

    const uppercase = original.toUpperCase();

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

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: