Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

Comience: escriba, pruebe e implemente sus primeras funciones

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

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

  • addMessage() , que expone una URL que acepta un valor de texto y lo escribe en Cloud Firestore.
  • makeUppercase() , que se activa en la escritura de Cloud Firestore y transforma el texto a mayúsculas.

Elegimos Cloud Firestore y las funciones JavaScript activadas por HTTP para esta muestra en parte porque estos activadores en segundo plano se pueden probar exhaustivamente a través de Firebase Local Emulator Suite . Este conjunto de herramientas también admite activadores de Realtime Database, PubSub, Auth y HTTP. Otros tipos de activadores en segundo plano, como los activadores de configuración remota, 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 , haga clic en Agregar proyecto .

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

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

  2. Si se le solicita, revise y acepte los términos de Firebase .

  3. Haga clic en Continuar .

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

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

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

  5. Haz clic en Crear proyecto (o Agregar Firebase , si usas un proyecto existente de Google Cloud).

Firebase aprovisiona recursos automáticamente para su proyecto de Firebase. Cuando finalice el proceso, accederá a la página de descripción general de su proyecto de Firebase en la consola de Firebase.

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 haya instalado Node.js y npm, instale Firebase CLI a través de su método preferido. Para instalar la CLI a través de npm, utilice:

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 inicializa el SDK de Firebase para Cloud Functions, crea un proyecto vacío que contiene dependencias y un código de muestra mínimo, y elige TypeScript o JavaScript para componer funciones. Para los fines de este tutorial, también deberá 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 a su directorio de proyectos de Firebase.
  3. Ejecute firebase init firestore . Para este tutorial, puede aceptar los valores predeterminados cuando se le soliciten las reglas y los archivos de índice de Firestore. Si aún no ha usado Cloud Firestore en este proyecto, también deberá seleccionar un modo de inicio y una ubicación para Firestore, como se describe en Primeros pasos con Cloud Firestore .
  4. Ejecute firebase init functions . La CLI le solicita que elija una base de código existente o que inicialice y nombre una nueva. Cuando recién está comenzando, una sola base de código en la ubicación predeterminada es adecuada; más adelante, a medida que su implementación se expanda, 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 brinda la opción de instalar dependencias con npm. Es seguro rechazar si desea administrar las dependencias de otra manera, aunque si lo hace, deberá ejecutar npm install antes de emular o implementar sus funciones.

Después de que estos comandos se completen con éxito, 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 requeridos e inicialice una aplicación

Una vez que haya completado las tareas de configuración, puede abrir el directorio de origen y comenzar a agregar código como se describe en las siguientes secciones. Para esta muestra, su proyecto debe importar los módulos Cloud Functions y Admin SDK mediante declaraciones de 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');

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

Estas líneas cargan los firebase-functions y firebase-admin e inicializan una instancia de la aplicación de admin desde la cual se pueden realizar cambios en Cloud Firestore. Dondequiera que esté disponible la compatibilidad con Admin SDK , como lo es para FCM, Authentication 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 for Cloud Functions Node cuando inicializa su proyecto. Para agregar bibliotecas de terceros a su proyecto, puede modificar package.json y ejecutar npm install . Para obtener más información, consulte Manejo de dependencias .

Agrega 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.`});
});

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 debe enviar una respuesta lo más rápido posible y diferir el trabajo con Cloud Firestore. La función HTTP addMessage() pasa un valor de texto al extremo HTTP y lo inserta en la base de datos en la ruta /messages/:documentId/original .

Agrega 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});
    });

La función makeUppercase() se ejecuta cuando se escribe en Cloud Firestore. La función ref.set define el documento para escuchar. Por motivos de rendimiento, debe 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 basadas en 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 se agota, lo que indica un error y se vuelve a intentar. Consulte Sincronización, asíncronismo y promesas .

Emular la ejecución de sus funciones

Firebase Local Emulator Suite le permite compilar 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 en su máquina. Ingrese esa URL en su navegador para abrir la interfaz de usuario de Emulator Suite.

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

    1. MY_PROJECT será reemplazado con su ID de 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 parecerse a: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme . Opcionalmente, puede cambiar el mensaje "mayúsculas" a un mensaje personalizado.

  4. Cree un nuevo mensaje abriendo la URL en una nueva pestaña en 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 indican que se ejecutaron las funciones addMessage() y makeUppercase() :

      i funciones: Comenzando la ejecución de "addMessage"

      i funciones: Comenzando la ejecución de "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 era "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 tiempo de ejecución de Node.js 14 recomendado, 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 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 extremo de la función HTTP. En su terminal, debería ver una línea como la siguiente:

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

    La URL contiene su ID de proyecto, así como una región para la función HTTP. Aunque no necesita preocuparse por eso ahora, algunas funciones HTTP de producción deberían 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 salida URL addMessage() de 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 ejecuta y redirige el navegador a Firebase console 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 Google Cloud Console . Si necesita eliminar funciones en desarrollo o producción, use Firebase CLI.

En producción, es posible que desee optimizar el rendimiento de las funciones y controlar los costos al establecer 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.

Revise el código de muestra completo

Aquí están las functions/index.js completas que contienen las funciones addMessage() y makeUppercase() . Estas funciones le 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');

// 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});
    });

Próximos pasos

En esta documentación, puede encontrar más información sobre los conceptos generales de Cloud Functions, así como guías para escribir funciones para manejar los tipos de eventos compatibles con Cloud Functions.

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

Videotutorial

Puede obtener más información sobre Cloud Functions viendo tutoriales en video. En este video, encontrará instrucciones detalladas sobre cómo comenzar con Cloud Functions, incluida la configuración de Node.js y CLI.