Google se compromete a impulsar la igualdad racial para las comunidades afrodescendientes. Obtén información al respecto.

Primeros pasos: Escribe, prueba e implementa tus primeras funciones

Para comenzar a usar Cloud Functions, sigue este instructivo, que comienza con las tareas de configuración obligatorias y, luego, te indica los pasos para crear, probar e implementar dos funciones relacionadas:

  • addMessage(), que expone una URL que acepta un valor de texto y lo escribe en Cloud Firestore
  • makeUppercase(), que se activa cuando se escribe en Cloud Firestore y aplica mayúsculas al texto

Para este ejemplo elegimos Cloud Firestore y funciones de JavaScript activadas por HTTP, en parte debido a que estos activadores en segundo plano pueden probarse completamente en Firebase Local Emulator Suite. Este conjunto de herramientas también es compatible con los activadores que admiten llamadas de Realtime Database, Pub/Sub, Auth y HTTP. Otros tipos de activadores en segundo plano, como Remote Config, Test Lab y Analytics, se pueden probar de forma interactiva con conjuntos de herramientas que no se describen en esta página.

En las siguientes secciones de este instructivo, se detallan los pasos necesarios para compilar, probar e implementar la muestra. Si solo quieres ejecutar e inspeccionar el código, ve a Revisa el código completo de la muestra.

Crea un proyecto de Firebase

  1. En Firebase console, haz clic en Agregar proyecto y selecciona o ingresa el Nombre del proyecto.

    Si ya tienes un proyecto de Google Cloud Platform (GCP), puedes seleccionarlo del menú desplegable para agregarle recursos de Firebase.

  2. Si vas a crear un proyecto nuevo, puedes editar el ID del proyecto (opcional).

    Firebase asignará de manera automática un ID único a tu proyecto de Firebase. Consulta la Información sobre los proyectos de Firebase para obtener detalles sobre cómo usa Firebase el ID del proyecto.

  3. Haz clic en Continuar.

  4. Configura Google Analytics para tu proyecto (opcional). Esto te permitirá tener una experiencia óptima con cualquiera de los siguientes productos de Firebase:

    Selecciona una cuenta de Google Analytics existente o crea una nueva cuando se te solicite.
    Si eliges crear una cuenta nueva, selecciona la ubicación de los informes de Analytics. Luego, acepta la configuración de uso compartido de datos y las condiciones de Google Analytics para el proyecto.

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

Firebase aprovisiona los recursos para tu proyecto de forma automática. Cuando finalice, verás la página de descripción general del proyecto en Firebase console.

Configura Node.js y Firebase CLI

Para escribir funciones, necesitarás un entorno de Node.js. Además, si quieres implementarlas en el entorno de ejecución de Cloud Functions, necesitarás Firebase CLI. Te recomendamos usar Node Version Manager para instalar Node.js y npm.

Una vez que hayas instalado Node.js y npm, instala Firebase CLI con el método que prefieras. Ejecuta el siguiente comando para instalar la CLI a través de npm:

npm install -g firebase-tools

Esto instala el comando firebase disponible de manera global. Si el comando falla, tal vez tengas que cambiar los permisos de npm. Para actualizar a la versión más reciente de firebase-tools, vuelve a ejecutar el mismo comando.

Inicializa el SDK de Firebase para Cloud Functions

Cuando inicializas el SDK de Firebase para Cloud Functions, creas un proyecto vacío con dependencias y código mínimo de muestra, y debes elegir TypeScript o JavaScript para redactar funciones.

Para inicializar tu proyecto, haz lo siguiente:

  1. Ejecuta firebase login para acceder a través del navegador y autenticar la herramienta de Firebase.
  2. Ve al directorio del proyecto de Firebase.
  3. Ejecuta firebase init functions. La herramienta te ofrece una opción para instalar las dependencias con npm. Es seguro rechazarla si quieres administrar las dependencias de otra manera, pero, si lo haces, deberás ejecutar npm install antes de emular o implementar tus funciones.
  4. La herramienta te ofrece dos opciones de lenguaje:

    En este instructivo, selecciona JavaScript.

Después de completar estos comandos de forma correcta, la estructura del proyecto será similar a la siguiente:

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 que se creó durante la inicialización contiene una clave importante: "engines": {"node": "10"}. Esta indica la versión de Node.js que se usará para escribir e implementar funciones. Puedes seleccionar otras versiones compatibles.

Importa los módulos requeridos para inicializar una app

Después de completar las tareas de configuración, puedes abrir el directorio fuente y comenzar a agregar código como se describe en las siguientes secciones. Para esta muestra, tu proyecto debe importar los módulos de Cloud Functions y del SDK de Admin con declaraciones require de Node. Agrega líneas como las siguientes al archivo index.js:

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

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

Estas líneas cargan los módulos firebase-functions y firebase-admin. Además, inicializan una instancia de app admin desde la cual se pueden realizar cambios de Cloud Firestore Dondequiera que esté disponible la compatibilidad con el SDK de Admin, como sucede con FCM, Authentication y Firebase Realtime Database, esta brinda una poderosa manera de integrar Firebase en Cloud Functions.

Firebase CLI instala automáticamente los módulos de Node y del SDK de Firebase para Cloud Functions cuando inicializas tu proyecto. Para agregar bibliotecas de terceros al proyecto, puedes modificar el archivo package.json y ejecutar npm install. Para obtener más información, consulta Cómo controlar dependencias.

Agrega la función addMessage()

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

// Take the text parameter passed to this HTTP endpoint and insert it into
// Cloud 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 Cloud Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've succesfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

La función addMessage() es un extremo de HTTP. Cada solicitud que se envía al extremo hace que los objetos Request y Response de estilo ExpressJS se pasen a la devolución de llamada onRequest().

Las funciones de HTTP son síncronas (similares a las funciones que admiten llamadas), por lo que debes enviar una respuesta lo más rápido posible y aplazar el trabajo con Cloud Firestore. La función de HTTP addMessage() transmite 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(), agrega 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 Cloud 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 Cloud Firestore.
      // Setting an 'uppercase' field in Cloud 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 que se debe escuchar. Por motivos de rendimiento, debes ser lo más específico posible.

Las llaves, por ejemplo, {documentId}, encierran “parámetros”, comodines que exponen las coincidencias de datos en la devolución de llamada.

Cloud Firestore activa la devolución de llamada onWrite() siempre que se escriban o actualicen datos en el documento especificado.

Las funciones controladas por eventos, como los eventos de Cloud Firestore son asíncronas. La función de devolución de llamada debería mostrar null, un objeto o una promesa. Si no se muestra nada, se agota el tiempo de espera de la función, se indica un error y se hace un nuevo intento. Consulta Síncrono, asíncrono y promesas.

Emula la ejecución de las funciones

En Firebase Local Emulator Suite puedes compilar y probar apps en tu máquina local en lugar de implementarlas en un proyecto de Firebase. Se recomienda enfáticamente hacer pruebas locales durante el desarrollo, en parte debido a que reduce el riesgo de cometer errores de codificación que podrían generar costos en un entorno de producción (por ejemplo, bucles infinitos).

Sigue estos pasos para emular las funciones:

  1. Ejecuta firebase emulators:start y verifica la salida de la URL de la IU de Emulator Suite. El valor predeterminado es localhost:4000, pero puede estar alojado en un puerto diferente de tu máquina. Ingresa esa URL en el navegador para abrir la IU de Emulator Suite.

  2. Verifica la salida del comando firebase emulators:start para encontrar la URL de la función de HTTP addMessage(). Tendrá un aspecto similar a http://localhost:5001/MY_PROJECT/us-central1/addMessage, pero con las siguientes diferencias:

    1. MY_PROJECT se reemplazará por el ID del proyecto.
    2. El puerto podría ser diferente en tu máquina local.
  3. Agrega la cadena de consulta ?text=uppercaseme al final de la URL de la función. Ahora debería verse así: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. De manera opcional, puedes cambiar el mensaje “uppercaseme” por un mensaje personalizado.

  4. Para crear un mensaje nuevo, abre la URL en una pestaña nueva del navegador.

  5. Observa los efectos de las funciones en la IU de Emulator Suite:

    1. En la pestaña Registros, deberías ver registros nuevos que indican 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ías ver un documento que contiene el mensaje original y su versión en mayúsculas (si originalmente era “uppercaseme”, ahora lo verás como “UPPERCASEME”).

Implementa funciones en un entorno de producción

Una vez que funcionen según lo esperado en el emulador, puedes proceder a implementar, probar y ejecutar tus funciones en el entorno de producción. Ten en cuenta que para llevar a cabo esta implementación en el entorno de ejecución recomendado de Node.js 10, tu proyecto debe tener el plan de facturación Blaze (prepago). Consulta los precios de Cloud Functions.

Para completar el instructivo, implementa las funciones y, luego, ejecuta addMessage() para activar makeUppercase().

  1. Ejecuta este comando para implementar las funciones:

    $ firebase deploy --only functions
    

    Después de ejecutarlo, Firebase CLI genera la URL de los extremos de la función de HTTP, si los hay. En la 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 del proyecto y una región para la función de HTTP. Si bien no debes preocuparte por esto, deberías especificar una ubicación para algunas funciones de HTTP de producción a fin de minimizar la latencia en la red.

    Si encuentras errores de acceso como “No se pudo autorizar el acceso al proyecto”, revisa el uso de alias en tu proyecto.

  2. Toma la URL de addMessage() que genera la CLI, agrega un parámetro de consulta de texto y ábrela en un navegador:

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

    La función se ejecuta y redirecciona el navegador a Firebase console en la ubicación de la base de datos en la que se almacena la string de texto. Este evento de escritura activa makeUppercase(), que escribe una versión de la string en mayúsculas.

Después de implementar y ejecutar funciones, puedes ver registros en Firebase console para Cloud Functions. Usa Firebase CLI para borrar funciones en desarrollo o producción.

Revisa el código completo de la muestra

Aquí se muestra la versión completa de functions/index.js que contiene las funciones addMessage() y makeUppercase(). Estas funciones te permiten pasarle un parámetro a un extremo HTTP que escribe un valor en Cloud Firestore y, luego, lo transforma mediante la conversión a mayúsculas de todos los caracteres de la string.

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

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

// Take the text parameter passed to this HTTP endpoint and insert it into
// Cloud 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 Cloud Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've succesfully 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 Cloud 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 Cloud Firestore.
      // Setting an 'uppercase' field in Cloud Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

Próximos pasos

En esta documentación, podrás obtener más detalles sobre los conceptos generales de Cloud Functions, además de guías sobre cómo escribir funciones para controlar los tipos de eventos compatibles con Cloud Functions.

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

Video instructivo

Mira videos instructivos para obtener más información sobre Cloud Functions. En este video, encontrarás una guía detallada sobre cómo comenzar con Cloud Functions, incluida la configuración de Node.js y la CLI.