Descripción general

Cloud Run Functions puede extender tus aplicaciones y servicios a través de la integración en las bases de datos de Google Cloud, como Firestore, Cloud Spanner, Cloud SQL, Cloud Bigtable y Memorystore, el servicio de caché de almacén de datos en memoria de Google Cloud.

En este lab, crearás Cloud Run Functions que se integren en Firestore, la base de datos de documentos NoSQL sin servidores de Google Cloud. Usarás el framework de Cloud Run Functions y la biblioteca cliente de Firestore para Node.js para crear funciones y configurar activadores que las ejecuten cuando se produzcan eventos en la base de datos.

El ciclo de vida de una función de Firestore suele incluir estos pasos:

• Esperar cambios en un documento específico de la base de datos de Firestore
• Activarse cuando ocurre un evento
• Realizar tareas con un objeto de datos que se recibe con una instantánea del documento afectado

Objetivos

En este lab, aprenderás a hacer lo siguiente:

• Configurar una base de datos de Firestore
• Desarrollar e implementar una función controlada por eventos para registrar información cuando se cree un documento en Firestore
• Desarrollar e implementar una función controlada por eventos para actualizar el contenido del documento
• Acceder a los Secrets y usarlos con Cloud Run Functions
• Usar la consola de Google Cloud para ver los registros generados por tu función

Configuración

Antes de hacer clic en el botón Comenzar lab

Nota: Lee estas instrucciones.

Los labs son cronometrados y no se pueden pausar. El cronómetro, que comienza a funcionar cuando haces clic en Comenzar lab, indica por cuánto tiempo tendrás a tu disposición los recursos de Google Cloud.

En este lab práctico de Qwiklabs, se te proporcionarán credenciales temporales nuevas para acceder a Google Cloud y realizar las actividades en un entorno de nube real, no en uno de simulación o demostración.

Requisitos

Para completar este lab, necesitarás lo siguiente:

• Acceso a un navegador de Internet estándar (se recomienda el navegador Chrome)
• Tiempo para completar el lab

Nota: Si ya tienes un proyecto o una cuenta personal de Google Cloud, no los uses para el lab. Nota: Si usas una Pixelbook, abre una ventana de incógnito para ejecutar el lab.

Activa Google Cloud Shell

Google Cloud Shell es una máquina virtual que cuenta con herramientas para desarrolladores. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud.

Google Cloud Shell proporciona acceso de línea de comandos a tus recursos de Google Cloud.

1. En la consola de Cloud, en la barra de herramientas superior derecha, haz clic en el botón Abrir Cloud Shell.

   

2. Haz clic en Continuar.

El aprovisionamiento y la conexión al entorno demorarán unos minutos. Cuando te conectes, habrás completado la autenticación, y el proyecto estará configurado con tu PROJECT_ID. Por ejemplo:

gcloud es la herramienta de línea de comandos de Google Cloud. Viene preinstalada en Cloud Shell y es compatible con el completado de línea de comando.

• Puedes solicitar el nombre de la cuenta activa con este comando:

gcloud auth list

Resultado:

Credentialed accounts: - @.com (active)

Resultado de ejemplo:

Credentialed accounts: - google1623327_student@qwiklabs.net

• Puedes solicitar el ID del proyecto con este comando:

gcloud config list project

Resultado:

[core] project =

Resultado de ejemplo:

[core] project = qwiklabs-gcp-44776a13dea667a6 Nota: La documentación completa de gcloud está disponible en la guía de descripción general de gcloud CLI .

Tarea 1: Configura el entorno

En esta tarea, configurarás las variables de entorno y habilitarás las APIs de servicios pertinentes que se necesitan para realizar este lab.

Configura las variables de entorno

Antes de crear Cloud Run Functions, debes configurar algunas variables de entorno.

1. Accede a la consola de Google Cloud con tus credenciales de lab y abre la ventana de terminal de Cloud Shell.

2. Ejecuta el siguiente comando en Cloud Shell para establecer las variables de entorno del ID del proyecto y la región.

   PROJECT_ID=$(gcloud config get-value project) REGION={{{project_0.default_region|set at lab start}}}

3. Crea una variable de entorno para el número de proyecto:

   PROJECT_NUMBER=$(gcloud projects list \ --filter="project_id:$PROJECT_ID" \ --format='value(project_number)')

4. Establece la región predeterminada para Cloud Run Functions:

   gcloud config set functions/region {{{project_0.default_region|set at lab start}}}

Habilita las APIs

1. Para habilitar las APIs de servicio que se necesitan para este lab, ejecuta el siguiente comando:

   gcloud services enable \ artifactregistry.googleapis.com \ cloudfunctions.googleapis.com \ cloudbuild.googleapis.com \ eventarc.googleapis.com \ run.googleapis.com \ logging.googleapis.com \ storage.googleapis.com \ pubsub.googleapis.com

Tarea 2: Configura Firestore

Para realizar las tareas de este lab, debes configurar una base de datos de Firestore. Firestore almacena datos en forma de documentos y colecciones. Para usar Cloud Run Functions con Firestore, primero debes configurar Firestore antes de implementar las funciones.

1. En la consola de Google Cloud, haz clic en la barra de búsqueda de la sección de navegación superior y escribe Firestore. Selecciona Firestore en los resultados de la búsqueda.

2. Haz clic en Crear una base de datos de Firestore.

3. Selecciona Edición Standard.

4. En Opciones de configuración, selecciona Firestore nativo.

5. En Reglas de seguridad, elige Abrir.

6. En Tipo de ubicación, haz clic en Región y, luego, selecciona la región que se estableció al inicio del lab en la lista.

   Nota: Si la lista de regiones no se completa, actualiza el navegador o vuelve a cargar el asistente desde el menú de la consola de Cloud.

7. Deja el resto de los parámetros de configuración con sus valores predeterminados y haz clic en Crear una base de datos.

Haz clic en Revisar mi progreso para verificar el objetivo. Configurar Firestore

Tarea 3: Desarrolla una función controlada por eventos para documentos nuevos de Firestore

Después de crear tu base de datos de Firestore, puedes desarrollar el código de la función. En esta tarea, escribirás el código fuente de la función que responde a la creación de documentos nuevos en la base de datos. Esta función registra información sobre los datos recibidos cuando se invoca la función de creación.

Configura tu directorio de trabajo

Las Cloud Functions de Firestore se invocan con una estructura de datos cloudevents que se puede decodificar usando búferes de protocolo con el módulo de NPM protobuf.js. Para obtener más información, consulta los vínculos que se proporcionan al final del lab.

1. Copia los archivos .proto y de dependencias necesarios en un directorio llamado firestore_functions:

   gcloud storage cp -R gs://cloud-training/CBL493/firestore_functions .

2. Cambia al directorio firestore_functions:

   cd firestore_functions

   El directorio firestore_functions también contiene archivos node.js y package.json vacíos que actualizarás en la siguiente subtarea.

Escribe el código de la función

1. En la barra de herramientas de Cloud Shell, haz clic en Abrir editor.

   Puedes cambiar entre Cloud Shell y el editor de código con las opciones Abrir editor y Abrir terminal, o bien haz clic en Abrir en una ventana nueva para dejar el editor abierto en una pestaña independiente.

2. En el editor, agrega el siguiente código al archivo firestore-functions/index.js:

   /** * Cloud Event Function triggered by a change to a Firestore document. */ const functions = require('@google-cloud/functions-framework'); const protobuf = require('protobufjs'); functions.cloudEvent('newCustomer', async cloudEvent => { console.log(`Function triggered by event on: ${cloudEvent.source}`); console.log(`Event type: ${cloudEvent.type}`); console.log('Loading protos...'); const root = await protobuf.load('data.proto'); const DocumentEventData = root.lookupType('google.events.cloud.firestore.v1.DocumentEventData'); console.log('Decoding data...'); const firestoreReceived = DocumentEventData.decode(cloudEvent.data); console.log('\nNew document:'); console.log(JSON.stringify(firestoreReceived.value, null, 2)); const documentData = firestoreReceived.value.fields; console.log('Document data:', documentData); }); El código usa la biblioteca de Node.js de Functions Framework para crear una función que procesa los datos entregados con la especificación de cloudEvent.

3. En el editor, agrega lo siguiente al archivo firestore-functions/package.json:

   { "name": "firestore_functions", "version": "0.0.1", "main": "index.js", "dependencies": { "@google-cloud/functions-framework": "^3.1.3", "protobufjs": "^7.2.2", "@google-cloud/firestore": "^6.0.0" } }

Actualiza los permisos de la cuenta de servicio

Debes otorgarle ciertos permisos al agente de servicio de Cloud Run Functions antes de implementar la función. Ejecuta los siguientes comandos en Cloud Shell.

1. Haz clic en Abrir terminal.

2. Configura una variable de entorno para la cuenta de servicio del agente de servicio de Cloud Run Functions:

   SERVICE_ACCOUNT=service-$PROJECT_NUMBER@gcf-admin-robot.iam.gserviceaccount.com

3. Para ver y obtener artefactos de Artifact Registry, otorga el rol artifactregistry.reader a la cuenta de servicio de Cloud Run Functions:

   gcloud projects add-iam-policy-binding $PROJECT_ID --member serviceAccount:$SERVICE_ACCOUNT --role roles/artifactregistry.reader Nota: Si en el paso anterior recibes un mensaje de error en el que se indica que la cuenta de servicio no existe o que la solicitud tiene credenciales de autenticación no válidas, sigue estos pasos:

4. Inhabilita la API de Cloud Functions:

   gcloud services disable cloudfunctions.googleapis.com

5. Vuelve a habilitar la API de Cloud Functions:

   gcloud services enable cloudfunctions.googleapis.com

6. Espera unos segundos y, luego, vuelve a ejecutar el comando para otorgar el rol artifactregistry.reader a la cuenta de servicio de Cloud Run Functions:

   gcloud projects add-iam-policy-binding $PROJECT_ID --member serviceAccount:$SERVICE_ACCOUNT --role roles/artifactregistry.reader

Implementa la función

• Para implementar la función, ejecuta el siguiente comando desde Cloud Shell:

  gcloud functions deploy newCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=newCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.created \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}' Firestore admite los eventos created, updated, deleted y written, que se especifican como la opción trigger-event-filter del comando de implementación. En el patrón de ruta de acceso, se indica que se deben supervisar todos los documentos de la colección customers.

  Después de que el comando se ejecute correctamente, este generará la URL del extremo de la función, como aparece en este resultado parcial de muestra del comando:

  ... state: ACTIVE updateTime: '2024-03-19T21:38:04.917134057Z' url: https://{{{project_0.default_region|set at lab start}}}-{{{project_0.default_region}}}.cloudfunctions.net/newCustomer Si recibes un mensaje de error cuando se implementa la función, espera unos minutos antes de volver a ejecutar el comando de implementación. Es posible que los permisos de la cuenta de servicio para Eventarc tarden un tiempo en propagarse.

Prueba la función

1. Navega a Firestore Studio en la consola de Cloud.

2. Para crear una nueva colección de documentos, haz clic en Iniciar colección.

3. En ID de la colección, escribe customers.

4. Para generar un ID para un documento en esta colección, haz clic en ID de documento.

5. Para este documento, agrega un campo con los siguientes valores:

   Nombre del campo	Tipo de campo	Valor del campo
   firstname	string	Lucas

6. Haz clic en Guardar.

7. Para verificar que se invocó la Cloud Function, en el menú de navegación (), haz clic en Cloud Run.

8. Haz clic en el nombre de la función newCustomer.

9. Haz clic en Registros.

10. Verifica que las entradas de registro generadas desde el código de la función estén presentes y que muestren los datos del documento de la base de datos que creaste.

    Es posible que debas hacer clic en Actualizar para ver las entradas de registro más recientes.

Haz clic en Revisar mi progreso para verificar el objetivo. Desarrollar una función controlada por eventos para documentos nuevos de Firestore

Tarea 4: Desarrolla una función controlada por eventos para que Firestore actualice un documento

En esta tarea, desarrollarás una función que se active cuando se actualice un documento en la base de datos de Firestore. La función agrega un campo nuevo al documento con un valor que se deriva de los valores de algunos de sus otros campos.

Escribe el código de la función

1. En el editor, agrega el siguiente código en el archivo firestore-functions/index.js:

   const Firestore = require('@google-cloud/firestore'); const firestore = new Firestore({ projectId: process.env.GOOGLE_CLOUD_PROJECT, }); functions.cloudEvent('updateCustomer', async cloudEvent => { console.log('Loading protos...'); const root = await protobuf.load('data.proto'); const DocumentEventData = root.lookupType( 'google.events.cloud.firestore.v1.DocumentEventData' ); console.log('Decoding data...'); const firestoreReceived = DocumentEventData.decode(cloudEvent.data); const resource = firestoreReceived.value.name; const affectedDoc = firestore.doc(resource.split('/documents/')[1]); // Fullname already exists, so don't update again to avoid infinite loop. if (firestoreReceived.value.fields.hasOwnProperty('fullname')) { console.log('Fullname is already present in document.'); return; } if (firestoreReceived.value.fields.hasOwnProperty('lastname')) { const lname = firestoreReceived.value.fields.lastname.stringValue; const fname = firestoreReceived.value.fields.firstname.stringValue; const fullname = `${fname} ${lname}` console.log(`Adding fullname --> ${fullname}`); await affectedDoc.update({ fullname: fullname }); } }); Puedes definir varias funciones con sus propios puntos de entrada en el mismo archivo main del proyecto y, luego, implementarlas por separado en Cloud Run Functions.

   Con este enfoque, todas las funciones pueden compartir el mismo conjunto de dependencias, incluso si algunas de ellas no las necesitan.

   Para minimizar la cantidad de dependencias necesarias para una función específica y reducir sus requisitos de memoria, se recomienda mantener el código fuente de cada función en su propio directorio de nivel superior con sus propios archivos de configuración del proyecto.

Implementa la función

1. Para implementar la nueva función, ejecuta el siguiente comando desde Cloud Shell:

   gcloud functions deploy updateCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=updateCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.updated \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}'

2. Verifica el resultado del comando que indica que la función se implementó y que el estado es Active.

Prueba la función

1. En la consola de Cloud, en Firestore Studio, selecciona los documentos existentes en la colección customers con el valor Lucas en el campo firstname.

2. En este documento, haz clic en Agregar campo.

3. Agrega un campo con los siguientes valores:

   Nombre del campo	Tipo de campo	Valor del campo
   lastname	string	Sherman

4. Haz clic en Guardar campo.

5. Espera unos segundos y, luego, verifica que se haya agregado un nuevo campo fullname al documento.

   Esto indica que tu Cloud Function updateCustomer se invocó cuando se actualizó el documento.

6. Para verificar que se invocó la Cloud Function, en el menú de navegación (), haz clic en Cloud Run.

7. Haz clic en el nombre de la función updateCustomer.

8. Haz clic en Registros.

9. Verifica que las entradas de registro generadas a partir del código de la función estén presentes y que indiquen que el campo fullname se agregó al documento.

   Es posible que debas hacer clic en Actualizar para ver las entradas de registro más recientes.

Haz clic en Revisar mi progreso para verificar el objetivo. Desarrollar una función controlada por eventos para que Firestore actualice un documento

Tarea 5: Usa Secrets con Cloud Functions

Secret Manager es un servicio de Google Cloud que almacena de forma segura datos como claves de APIs, contraseñas, certificados, credenciales y otra información sensible. Puedes acceder a estos secretos desde Cloud Run Functions o desde otros servicios para usarlos en la lógica de tu función o en la implementación de un servicio.

En esta tarea, crearás y almacenarás una credencial como un secreto en Secret Manager. Desarrollarás una función para acceder a la clave en la lógica de tu función.

Crea un secreto

1. Para crear y usar secretos, ejecuta el siguiente comando en Cloud Shell y habilita la API de Secret Manager:

   gcloud services enable secretmanager.googleapis.com

2. Crea y almacena un secreto llamado api-cred con el valor secret_api_key en Secret Manager:

   echo -n "secret_api_key" | gcloud secrets create api-cred --replication-policy="automatic" --data-file=- Con la política de replicación, se determina qué regiones se usan para almacenar los secretos y sus versiones. Para especificar una o más regiones en las que se puede replicar un secreto, puedes establecer la política de replicación en user-managed.

Otorga acceso

Para acceder a un secreto, la cuenta de servicio del entorno de ejecución de tu función debe tener acceso a este.

• De forma predeterminada, Cloud Run Functions usa la cuenta de servicio predeterminada de Compute Engine como la cuenta de servicio de entorno de ejecución de una función.

  Para autenticar con Secret Manager, otorga el rol Usuario con acceso a secretos de Secret Manager a la cuenta de servicio predeterminada de Compute Engine:

  gcloud secrets add-iam-policy-binding api-cred --member=serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com --project=$PROJECT_ID --role='roles/secretmanager.secretAccessor' Nota: Para el uso en producción, debes configurar tu función para que se autentique con su propia cuenta de servicio administrada por el usuario, a la que se le asigna el conjunto de roles con menos permisos que es necesario para que la función complete sus tareas.

Accede al secreto desde tu función

En esta subtarea, modificarás la función newCustomer desarrollada anteriormente para acceder al secreto.

• En el editor, agrega el siguiente código a la función newCustomer en el archivo index.js. En el cuerpo de la función, al final, agrega el código después de la última sentencia console.log:

  // BEGIN access a secret const fs = require('fs/promises'); try { const secret = await fs.readFile('/etc/secrets/api_cred/latest', { encoding: 'utf8' }); // use the secret. For lab testing purposes, we log the secret. console.log('secret: ', secret); } catch (err) { console.log(err); } // End access a secret El código lee el valor del secreto de un archivo que se activó en un volumen al que la función puede acceder. Configurarás este método de acceso al secreto cuando implementes la función en el siguiente paso.

Vuelve a implementar la función

1. En Cloud Shell, vuelve a implementar la función newCustomer con el secreto:

   gcloud functions deploy newCustomer \ --gen2 \ --runtime=nodejs20 \ --region={{{project_0.default_region|set at lab start}}} \ --trigger-location={{{project_0.default_region|set at lab start}}} \ --source=. \ --entry-point=newCustomer \ --trigger-event-filters=type=google.cloud.firestore.document.v1.created \ --trigger-event-filters=database='(default)' \ --trigger-event-filters-path-pattern=document='customers/{name}' \ --set-secrets '/etc/secrets/api_cred/latest=api-cred:latest' La opción de comando de implementación set-secrets especifica la ruta de acceso: /etc/secrets/api_cred y la ruta de acceso al secreto: /latest.

   Si haces referencia a un secreto como un volumen, la función accede al valor del secreto más reciente de Secret Manager cada vez que el archivo se lee desde el disco.

   Tu función también puede acceder a una versión específica del valor del secreto como una variable de entorno. Consulta la documentación sobre el uso de secretos con Cloud Run Functions para obtener más información.

2. Después de implementar la función, verifica que tenga acceso al secreto:

   gcloud functions describe newCustomer

   El resultado del comando describe incluye información sobre el secreto. Este es un resultado parcial del comando:

   ... secretVolumes: - mountPath: /etc/secrets/api_cred projectId: '{{{project_0.project_id|Project_ID}}}' secret: api-cred versions: - path: /latest version: latest ...

Prueba la función

1. Para probar la función, repite la prueba de la tarea anterior para agregar un nuevo documento de cliente desde Firestore Studio en la consola de Cloud.

2. Para ver los registros de la función en la consola de Cloud, en el menú de navegación (), haz clic en Cloud Run.

3. Haz clic en el nombre de la función newCustomer.

4. Para ver la actividad de la función, haz clic en Registros.

   Verifica que la entrada para registrar el valor de la clave del secreto:

   secret: secret_api_key Nota: Si bien no es una práctica general registrar el valor de los secretos, este paso se usa para confirmar que la función tiene acceso a su valor y que puede usar el secreto en su código.

Haz clic en Revisar mi progreso para verificar el objetivo. Usar secretos con Cloud Run Functions

¡Felicitaciones!

En este lab, configuraste una base de datos de Firestore y desarrollaste una Cloud Function controlada por eventos que se activa cuando se crea un documento nuevo en la base de datos. También desarrollaste una función para agregar un campo nuevo a un documento cuando se actualiza. Además, creaste un secreto y accediste a él desde una Cloud Function y usaste registros para verificar su valor.

Próximos pasos/Más información

Para obtener más información sobre Cloud Run Functions para Firestore y otros temas, consulta la siguiente documentación:

• Activadores de Firestore
• Búferes de protocolo
• Cloud Functions para Firebase

Copyright 2020 Google LLC. All rights reserved. Google y el logotipo de Google son marcas de Google LLC. Los demás nombres de productos y empresas pueden ser marcas de las respectivas empresas a las que estén asociados.