Cómo pausar y reanudar un flujo de trabajo con devoluciones de llamada y Hojas de cálculo de Google

Hojas de cálculo de Google es una solución de hojas de cálculo basada en la nube que admite la colaboración en tiempo real y proporciona herramientas para visualizar, procesar y comunicar datos.

En este instructivo, se muestra cómo crear e implementar un flujo de trabajo que crea un extremo de devolución de llamada (o webhook), guarda la URL de devolución de llamada en Hojas de cálculo de Google, pausa la ejecución y, luego, espera la aprobación humana a través de la hoja de cálculo de Hojas de cálculo para reiniciar el flujo de trabajo. Obtén más información para usar devoluciones de llamada.

Objetivos

En este instructivo, podrás:

  1. Crea una carpeta nueva en Google Drive. Esta carpeta se usa para almacenar tu hoja de cálculo y permite que el flujo de trabajo escriba en ella.
  2. Crea una hoja de cálculo de Hojas de cálculo de Google para capturar una aprobación y, luego, inicia una devolución de llamada a un flujo de trabajo.
  3. Usa Google Apps Script, una plataforma de JavaScript basada en la nube que te permite crear, leer y editar productos de Google Workspace de forma programática, para activar la reanudación de un flujo de trabajo pausado cada vez que se aprueba una solicitud a través de una actualización de la hoja de cálculo.
  4. Crea e implementa un flujo de trabajo que llame al conector de la API de Hojas de cálculo de Google para agregar datos a la hoja de cálculo. El flujo de trabajo se ejecuta, se pausa y, luego, se reanuda cuando se aprueba una devolución de llamada a través de la hoja de cálculo. Obtén más información sobre los conectores de Workflows.
  5. Prueba todo el proceso y confirma que el flujo de trabajo se desarrolle según lo esperado.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.

Es posible que los usuarios Google Cloud nuevos cumplan con los requisitos para obtener una prueba gratuita.

En el instructivo, también se usa Google Workspace. Los servicios empresariales que no se incluyen en las aplicaciones gratuitas de Google para consumidores son facturables.

Antes de comenzar

Puedes ejecutar algunos de los siguientes comandos en la consola de Google Cloud o con Google Cloud CLI en tu terminal o Cloud Shell.

Es posible que las restricciones de seguridad que define tu organización no te permitan completar los siguientes pasos. Para obtener información sobre la solución de problemas, consulta Desarrolla aplicaciones en un entorno Google Cloud restringido.

Console

  1. En la Google Cloud consola, en la página del selector de proyectos, selecciona o crea un Google Cloud proyecto.

    Ir al selector de proyectos

  2. Asegúrate de tener habilitada la facturación para tu Google Cloud proyecto. Obtén información para verificar si la facturación está habilitada en un proyecto.

  3. Habilita las APIs de Compute Engine, Hojas de cálculo y Workflows.

    Habilita las API

  4. Toma nota de la cuenta de servicio predeterminada de Compute Engine, ya que la asociarás con el flujo de trabajo en este instructivo con fines de prueba. Los proyectos nuevos que habilitaron la API de Compute Engine tienen esta cuenta de servicio creada con el rol básico de Editor de IAM y con el siguiente formato de correo electrónico:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Puedes encontrar el número del proyecto en la página de bienvenida de la consola de Google Cloud .

    Para entornos de producción, recomendamos crear una cuenta de servicio nueva y otorgarle uno o más roles de IAM que contengan los permisos mínimos requeridos y seguir el principio de privilegio mínimo.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Asegúrate de tener habilitada la facturación para tu Google Cloud proyecto. Obtén información para verificar si la facturación está habilitada en un proyecto.

  3. Habilita las APIs de Compute Engine, Hojas de cálculo y Workflows.

    gcloud services enable \
    compute.googleapis.com \
    sheets.googleapis.com \
    workflows.googleapis.com

  4. Toma nota de la cuenta de servicio predeterminada de Compute Engine, ya que la asociarás con el flujo de trabajo en este instructivo con fines de prueba. Los proyectos nuevos que habilitaron la API de Compute Engine tienen esta cuenta de servicio creada con el rol básico de Editor de IAM y con el siguiente formato de correo electrónico:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Puedes recuperar el número de tu proyecto de la siguiente manera:

    gcloud projects describe PROJECT_ID

    Para entornos de producción, recomendamos crear una cuenta de servicio nueva y otorgarle uno o más roles de IAM que contengan los permisos mínimos requeridos y seguir el principio de privilegio mínimo.

Crea una carpeta nueva en Google Drive

Crea una carpeta nueva en Google Drive. Esta carpeta se usa para almacenar tu hoja de cálculo. Si configuras un permiso para la carpeta compartida, tu flujo de trabajo podrá escribir en la hoja de cálculo.

  1. Ve a drive.google.com.
  2. Haz clic en Nuevo > Nueva carpeta.
  3. Ingresa un nombre para la carpeta.
  4. Haz clic en Crear.
  5. Haz clic con el botón derecho en la carpeta nueva y selecciona Compartir.

  6. Agrega la dirección de correo electrónico de la cuenta de servicio predeterminada de Compute Engine.

    Esto le otorga a la cuenta de servicio acceso a la carpeta. Cuando asocies la cuenta de servicio a tu flujo de trabajo, este tendrá acceso de edición a cualquier archivo de la carpeta. Obtén más información para compartir archivos, carpetas y unidades.

  7. Selecciona el rol de Editor.

  8. Desmarca la casilla de verificación Notificar a las personas.

  9. Haz clic en Compartir

Crea una hoja de cálculo con Hojas de cálculo de Google

Cuando creas una hoja de cálculo con Hojas de cálculo de Google, esta se guarda en Google Drive. De forma predeterminada, la hoja de cálculo se guarda en tu carpeta raíz de Drive. No existe la opción de crear una hoja de cálculo directamente en una carpeta especificada con la API de Hojas de cálculo de Google. Sin embargo, existen alternativas, como mover la hoja de cálculo a una carpeta específica después de crearla, como se hace en este ejemplo. Para obtener más información, consulta Cómo trabajar con carpetas de Google Drive.

  1. Ve a sheets.google.com.

  2. Haz clic en Nuevo Plus.

    Se creará y abrirá la nueva hoja de cálculo. Cada hoja de cálculo tiene un valor de spreadsheetId único que contiene letras, números, guiones o guiones bajos. Puedes encontrar el ID de la hoja de cálculo en una URL de Hojas de cálculo de Google:

    https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0

  3. Anota este ID, ya que lo necesitarás cuando crees tu flujo de trabajo.

  4. Agrega encabezados de columna para que coincidan con el siguiente ejemplo:

    Ejemplo de hoja de cálculo para registrar aprobaciones

    Ten en cuenta que el valor de la columna G, ¿Aprobado?, se usa para iniciar devoluciones de llamada en el flujo de trabajo.

  5. Mueve la hoja de cálculo a la carpeta de Google Drive que creaste anteriormente:

    1. En la hoja de cálculo, selecciona Archivo > Mover.
    2. Navega a la carpeta que creaste.
    3. Haz clic en Mover.

También puedes usar el conector de la API de Google Sheets para crear una hoja de cálculo. Ten en cuenta que, cuando se usa el conector, el spreadsheetId se puede recuperar del resultado de resp. Por ejemplo: 

- create_spreadsheet:
    call: googleapis.sheets.v4.spreadsheets.create
    args:
      body:
      connector_params:
        scopes: ${driveScope}
    result: resp
- assign_sheet_id:
    assign:
      - sheetId: ${resp.spreadsheetId}

Extiende Hojas de cálculo de Google con Apps Script

Apps Script te permite crear, leer y editar Hojas de cálculo de Google de forma programática. La mayoría de las secuencias de comandos diseñadas para Hojas de cálculo manipulan arrays para interactuar con las celdas, las filas y las columnas de una hoja de cálculo. Para obtener una introducción al uso de Apps Script con Hojas de cálculo de Google, consulta la Guía de inicio rápido de funciones personalizadas.

  1. Crea un proyecto de Apps Script desde Hojas de cálculo de Google:

    1. Abre tu hoja de cálculo de Hojas de cálculo.
    2. Selecciona Extensiones > Apps Script.
    3. En el editor de secuencias de comandos, haz clic en Proyecto sin título.
    4. Asigna un nombre al proyecto y haz clic en Cambiar nombre.

    Tu secuencia de comandos ahora está vinculada a tu hoja de cálculo, lo que le otorga habilidades especiales para alterar la interfaz de usuario o responder cuando se abre la hoja de cálculo.

    Un proyecto de secuencia de comandos representa una colección de archivos y recursos de Apps Script. Los archivos de código en un proyecto de secuencia de comandos tienen una extensión .gs.

  2. Puedes usar Apps Script para escribir funciones personalizadas que puedes usar en Hojas de cálculo de Google como si fueran funciones integradas. Las funciones personalizadas se crean con JavaScript estándar. Crea una función:

    1. Abre tu proyecto de Apps Script.
    2. Haz clic en Editor .
    3. Un archivo de secuencia de comandos aparece como un archivo de proyecto llamado Code.gs. Para editar el archivo, selecciónalo.

    4. Reemplaza cualquier código del editor de secuencias de comandos por el siguiente código, que lee los datos de tu hoja de cálculo y los pasa como entrada a la ejecución de un flujo de trabajo:

      function handleEdit(e) {
  var range = e.range.getA1Notation();
  var sheet = e.source;

  if (range.length > 1 && range[0] === 'G') {
    if (e.value == "TRUE") {
      Logger.log("Approved: TRUE");

      var row = range.slice(1);
      var url = sheet.getRange('E' + row).getCell(1, 1).getValue();
      var approver = sheet.getRange('F' + row).getCell(1, 1).getValue();

      callback(url, approver);
    }
    else {
      Logger.log("Approved: FALSE");
    }
  }
}

function callback(url, approver) {
  const headers = {
    "Authorization": "Bearer " + ScriptApp.getOAuthToken()
  };

  var payload = {
    'approver': approver
  };

  const params = {
    "method": 'POST',
    "contentType": 'application/json',
    "headers": headers,
    "payload": JSON.stringify(payload)
  };


  Logger.log("Workflow callback request to " + url);
  var response = UrlFetchApp.fetch(url, params);
  Logger.log(response);
}

    5. Haz clic en Guardar .

  3. Los activadores instalables de Apps Script permiten que un proyecto de secuencia de comandos ejecute una función especificada cuando se cumplen ciertas condiciones, como cuando se abre o edita una hoja de cálculo. Crea un activador:

    1. Abre tu proyecto de Apps Script.
    2. Haz clic en Activadores .
    3. Haz clic en Add Trigger.
    4. En el diálogo Add Trigger for YOUR_PROJECT_NAME, configura el activador de la siguiente manera:
      1. En la lista Elige qué función ejecutar, selecciona handleEdit.
      2. En la lista Elige qué implementación se debe ejecutar, selecciona Head.
      3. En la lista Selecciona la fuente del evento, elige Desde hoja de cálculo.
      4. En la lista Selecciona el tipo de evento, selecciona On edit.
      5. En la lista Configuración de notificaciones de error, selecciona Notificarme diariamente.
    5. Haz clic en Guardar.

    6. Si recibes un mensaje para elegir una Cuenta de Google, selecciona la cuenta adecuada y, luego, haz clic en Permitir.

      Esto permite que tu proyecto de Apps Script vea, edite, cree y borre tus hojas de cálculo de Hojas de Google, y que se conecte a un servicio externo.

  4. Un archivo de manifiesto de un proyecto de Apps Script es un archivo JSON que especifica la información básica del proyecto que Apps Script necesita para ejecutar una secuencia de comandos correctamente. Ten en cuenta que el editor de Apps Script oculta los archivos de manifiesto de forma predeterminada para proteger la configuración de tu proyecto de Apps Script. Edita el archivo de manifiesto:

    1. Abre tu proyecto de Apps Script.
    2. Haz clic en Configuración del proyecto .
    3. Selecciona la casilla de verificación Mostrar el archivo de manifiesto "appsscript.json" en el editor.
    4. Haz clic en Editor .
    5. El archivo de manifiesto aparece como un archivo de proyecto llamado appsscript.json. Para editar el archivo, selecciónalo.

    6. El campo oauthScopes especifica un array de cadenas. Para establecer los permisos de autorización que usa tu proyecto, agrega un array con los permisos que deseas admitir. Por ejemplo: 

      {
  "timeZone": "America/Toronto",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/spreadsheets"
  ]
}

      Esto establece permisos explícitos para lo siguiente:

      • Se conecta a un servicio externo.
      • Ver, editar, configurar y borrar tus Google Cloud datos, y ver la dirección de correo electrónico de tu Cuenta de Google
      • Vea, edite, cree y borre todos sus archivos de Hojas de cálculo de Google

    7. Haz clic en Guardar .

Implementa un flujo de trabajo que escribe en una hoja de cálculo y usa devoluciones de llamada

Implementa un flujo de trabajo que se ejecute, se detenga y, luego, se reanude cuando se apruebe una devolución de llamada a través de una hoja de cálculo. El flujo de trabajo escribe en una hoja de cálculo de Sheets con el conector de la API de Google Sheets.

Console

  1. En la consola de Google Cloud , ve a la página Workflows:

    Ir a Workflows

  2. Haz clic en  Crear.

  3. Ingresa un nombre para el flujo de trabajo nuevo: workflows-awaits-callback-sheets.

  4. En la lista Región, selecciona us-central1 (Iowa).

  5. En Cuenta de servicio, selecciona la cuenta de servicio predeterminada de Compute Engine (PROJECT_NUMBER-compute@developer.gserviceaccount.com).

  6. Haz clic en Siguiente.

  7. En el editor de flujos de trabajo, ingresa la siguiente definición para el flujo de trabajo:

    main:
  steps:
    - init:
        assign:
        # Replace with your sheetId and make sure the service account
        # for the workflow has write permissions to the sheet
        - sheetId: "10hieAH6b-oMeIVT_AerSLNxQck14IGhgi8ign-x2x8g"
    - before_sheets_callback:
        call: sys.log
        args:
          severity: INFO
          data: ${"Execute steps here before waiting for callback from sheets"}
    - wait_for_sheets_callback:
        call: await_callback_sheets
        args:
          sheetId: ${sheetId}
        result: await_callback_result
    - after_sheets_callback:
        call: sys.log
        args:
          severity: INFO
          data: ${"Execute steps here after receiving callback from sheets"}
    - returnResult:
        return: ${await_callback_result}

await_callback_sheets:
    params: [sheetId]
    steps:
        - init:
            assign:
              - project_id: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}
              - location: ${sys.get_env("GOOGLE_CLOUD_LOCATION")}
              - workflow_id: ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_ID")}
              - execution_id: ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_EXECUTION_ID")}
        - create_callback:
            call: events.create_callback_endpoint
            args:
              http_callback_method: POST
            result: callback_details
        - save_callback_to_sheets:
            call: googleapis.sheets.v4.spreadsheets.values.append
            args:
                range: ${"Sheet1!A1:G1"}
                spreadsheetId: ${sheetId}
                valueInputOption: RAW
                body:
                    majorDimension: "ROWS"
                    values:
                      - ["${project_id}", "${location}", "${workflow_id}", "${execution_id}", "${callback_details.url}", "", "FALSE"]
        - log_and_await_callback:
            try:
              steps:
                - log_await_start:
                    call: sys.log
                    args:
                      severity: INFO
                      data: ${"Started waiting for callback from sheet " + sheetId}
                - await_callback:
                    call: events.await_callback
                    args:
                      callback: ${callback_details}
                      timeout: 3600
                    result: callback_request
                - log_await_stop:
                    call: sys.log
                    args:
                      severity: INFO
                      data: ${"Stopped waiting for callback from sheet " + sheetId}
            except:
                as: e
                steps:
                    - log_error:
                        call: sys.log
                        args:
                            severity: "ERROR"
                            text: ${"Received error " + e.message}
        - check_null_await_result:
            switch:
              - condition: ${callback_request == null}
                return: null
        - log_await_result:
            call: sys.log
            args:
              severity: INFO
              data: ${"Approved by " + callback_request.http_request.body.approver}
        - return_await_result:
            return: ${callback_request.http_request.body}

  8. Asegúrate de reemplazar el valor del marcador de posición sheetId por tu spreadsheetId.

  9. Haz clic en Implementar.

gcloud

  1. Crea un archivo de código fuente para tu flujo de trabajo:

    touch workflows-awaits-callback-sheets.yaml

  2. En un editor de texto, copia el siguiente flujo de trabajo en tu archivo de código fuente:

    main:
  steps:
    - init:
        assign:
        # Replace with your sheetId and make sure the service account
        # for the workflow has write permissions to the sheet
        - sheetId: "10hieAH6b-oMeIVT_AerSLNxQck14IGhgi8ign-x2x8g"
    - before_sheets_callback:
        call: sys.log
        args:
          severity: INFO
          data: ${"Execute steps here before waiting for callback from sheets"}
    - wait_for_sheets_callback:
        call: await_callback_sheets
        args:
          sheetId: ${sheetId}
        result: await_callback_result
    - after_sheets_callback:
        call: sys.log
        args:
          severity: INFO
          data: ${"Execute steps here after receiving callback from sheets"}
    - returnResult:
        return: ${await_callback_result}

await_callback_sheets:
    params: [sheetId]
    steps:
        - init:
            assign:
              - project_id: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}
              - location: ${sys.get_env("GOOGLE_CLOUD_LOCATION")}
              - workflow_id: ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_ID")}
              - execution_id: ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_EXECUTION_ID")}
        - create_callback:
            call: events.create_callback_endpoint
            args:
              http_callback_method: POST
            result: callback_details
        - save_callback_to_sheets:
            call: googleapis.sheets.v4.spreadsheets.values.append
            args:
                range: ${"Sheet1!A1:G1"}
                spreadsheetId: ${sheetId}
                valueInputOption: RAW
                body:
                    majorDimension: "ROWS"
                    values:
                      - ["${project_id}", "${location}", "${workflow_id}", "${execution_id}", "${callback_details.url}", "", "FALSE"]
        - log_and_await_callback:
            try:
              steps:
                - log_await_start:
                    call: sys.log
                    args:
                      severity: INFO
                      data: ${"Started waiting for callback from sheet " + sheetId}
                - await_callback:
                    call: events.await_callback
                    args:
                      callback: ${callback_details}
                      timeout: 3600
                    result: callback_request
                - log_await_stop:
                    call: sys.log
                    args:
                      severity: INFO
                      data: ${"Stopped waiting for callback from sheet " + sheetId}
            except:
                as: e
                steps:
                    - log_error:
                        call: sys.log
                        args:
                            severity: "ERROR"
                            text: ${"Received error " + e.message}
        - check_null_await_result:
            switch:
              - condition: ${callback_request == null}
                return: null
        - log_await_result:
            call: sys.log
            args:
              severity: INFO
              data: ${"Approved by " + callback_request.http_request.body.approver}
        - return_await_result:
            return: ${callback_request.http_request.body}

  3. Asegúrate de reemplazar el valor del marcador de posición sheetId por tu spreadsheetId.

  4. Para implementar el flujo de trabajo, ingresa el siguiente comando:

    gcloud workflows deploy workflows-awaits-callback-sheets \
    --source=workflows-awaits-callback-sheets.yaml \
    --location=us-central1 \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Reemplaza PROJECT_NUMBER por el número de tu proyecto Google Cloud. Puedes recuperar el número de tu proyecto de la siguiente manera:

    gcloud projects describe PROJECT_ID

Prueba el flujo de extremo a extremo

Ejecuta el flujo de trabajo para probar el flujo de extremo a extremo. Ejecuta la definición actual del flujo de trabajo asociada con el flujo de trabajo.

Console

  1. En la consola de Google Cloud , ve a la página Workflows:

    Ir a Workflows

  2. En la página Flujos de trabajo, selecciona el flujo de trabajo workflows-awaits-callback-sheets para ir a su página de detalles.

  3. En la página Detalles del flujo de trabajo, haz clic en Ejecutar.

  4. Haz clic de nuevo en Ejecutar.

    Se iniciará el flujo de trabajo y su estado de ejecución debería ser En ejecución. Los registros también indican que el flujo de trabajo está en pausa y en espera:

    Execute steps here before waiting for callback from sheets
...
Started waiting for callback from sheet 1JlNFFnqs760M_KDqeeeDc_qtrABZDxoalyCmRE39dpM

  5. Verifica que el flujo de trabajo haya escrito los detalles de la devolución de llamada en una fila de tu hoja de cálculo.

    Por ejemplo, deberías ver el ID de ejecución del flujo de trabajo en la columna Execution ID, un extremo de devolución de llamada en la columna Callback URL y FALSE en la columna Approved?.

  6. En la hoja de cálculo, cambia FALSE por TRUE.

    Después de un minuto o dos, la ejecución debería reanudarse y, luego, completarse con un estado de ejecución Correcto.

gcloud

  1. Abre una terminal.

  2. Ejecuta el flujo de trabajo:

      gcloud workflows run workflows-awaits-callback-sheets

    El flujo de trabajo se inicia y el resultado debería indicar que está pausado y en espera:

      Waiting for execution [a8361789-90e0-467f-8bd7-ea1c81977820] to complete...working.

  3. Verifica que el flujo de trabajo haya escrito los detalles de la devolución de llamada en una fila de tu hoja de cálculo.

    Por ejemplo, deberías ver el ID de ejecución del flujo de trabajo en la columna Execution ID, un extremo de devolución de llamada en la columna Callback URL y FALSE en la columna Approved?.

  4. En la hoja de cálculo, cambia FALSE por TRUE.

    Después de un minuto o dos, la ejecución debería reanudarse y, luego, completarse con un estado de ejecución de SUCCEEDED.

Limpia

Si creaste un proyecto nuevo para este instructivo, bórralo. Si usaste un proyecto existente y deseas conservarlo sin los cambios que se agregaron en este instructivo, borra los recursos creados para el instructivo.

Borra el proyecto

La manera más fácil de eliminar la facturación es borrar el proyecto que creaste para el instructivo.

Para borrar el proyecto, sigue estos pasos:

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

Borra los recursos creados en este instructivo

  1. Cómo borrar archivos en Google Drive
  2. Borra un flujo de trabajo.

¿Qué sigue?