Representa datos complejos con un recurso personalizado

Programa de la versión alfa de Gemini: Flows está disponible como parte del programa de la versión alfa de Gemini.

En esta guía, se explica cómo definir recursos personalizados para los flujos de Google Workspace.

Los recursos personalizados son estructuras de datos personalizadas que puedes definir para agrupar varias variables. Por ejemplo, para crear un cliente potencial de CRM, pasa un recurso personalizado que contenga una dirección de correo electrónico, una dirección y un nombre.

Estas son las dos formas de definir recursos personalizados:

• Como referencia: Cuando generas un recurso personalizado como referencia, devuelves el recurso personalizado por su ID en lugar del objeto de recurso personalizado completo. Esto mejora el rendimiento, ya que reduce la cantidad de datos que se transfieren entre los pasos del flujo. Cuando los datos requieren búsquedas secundarias, devolver su ID es útil para realizar esas búsquedas.
• Como valor: Usa este método cuando los datos se deban recuperar durante la ejecución o cuando el recurso personalizado sea pequeño y no contenga datos sensibles.

Cómo generar un recurso personalizado como referencia

Si generas un recurso personalizado como referencia, puedes devolver el recurso personalizado por su ID en lugar del objeto de recurso personalizado completo. Si un recurso personalizado es grande o complejo, pasar solo el ID mejora el rendimiento, ya que reduce los datos transferidos entre los pasos del flujo.

Para generar un recurso personalizado como referencia, edita el archivo de manifiesto y el código del paso.

Edita el archivo de manifiesto

En el archivo de manifiesto, haz lo siguiente:

1. Especifica un workflowResourceDefinitions y asígnale un id, un array fields[] y un providerFunction. workflowResourceDefinitions es una estructura que define los tipos de datos y el contenido del recurso personalizado.

2. Dentro del array fields[], especifica los campos individuales que componen el recurso personalizado, en este ejemplo llamados field_1 y field_2.

3. El valor de providerFunction debe coincidir con el nombre de una función en el código del paso. El providerFunction recupera el contenido del recurso personalizado real cuando es necesario.

   JSON

   {
       "workflowResourceDefinitions": [
           {
               "id": "resource_id",
               "name": "Custom Resource",
               "fields": [
                   {
                       "selector": "field_1",
                       "name": "Field 1",
                       "dataType": {
                           "basicType": "STRING"
                       }
                   },
                   {
                       "selector": "field_2",
                       "name": "Field 2",
                       "dataType": {
                           "basicType": "STRING"
                       }
                   }
               ],
               "providerFunction": "onMessageResourceFunction"
           }
       ]
   }
   

4. En outputs[], especifica una variable de salida que devuelva un conjunto dinámico de variables de salida. La variable de salida tiene un dataType con la propiedad resourceType. El valor de cardinality debe ser SINGLE.

   JSON

   "outputs": [{
           "id": "resource_data",
           "description": "Resource Data",
           "cardinality": "SINGLE",
           "dataType": {
             "resourceType": { "workflowResourceDefinitionId": "resource_id" }
           }
         }]
   

Este es un archivo de manifiesto completo que define un recurso personalizado:

JSON

{
    "timeZone": "America/Los_Angeles",
    "exceptionLogging": "STACKDRIVER",
    "runtimeVersion": "V8",
    "addOns": {
        "common": {
            "name": "Calculator",
            "logoUrl": "https://www.gstatic.com/images/branding/productlogos/calculator_search/v1/web-24dp/logo_calculator_search_color_1x_web_24dp.png",
            "useLocaleFromApp": true
        },
        "flows": {
            "workflowElements": [
                {
                    "id": "getResourceData",
                    "state": "ACTIVE",
                    "name": "Get Resource by ID",
                    "description": "Get Resource by ID",
                    "workflowAction": {
                        "outputs": [
                            {
                                "id": "resource_data",
                                "description": "Resource Data",
                                "cardinality": "SINGLE",
                                "dataType": {
                                    "resourceType": {
                                        "workflowResourceDefinitionId": "resource_id"
                                    }
                                }
                            }
                        ],
                        "onConfigFunction": "onConfigResourceFunction",
                        "onExecuteFunction": "onExecuteResourceFunction"
                    }
                }
            ],
            "workflowResourceDefinitions": [
                {
                    "id": "resource_id",
                    "name": "Custom Resource",
                    "fields": [
                        {
                            "selector": "field_1",
                            "name": "Field 1",
                            "dataType": {
                                "basicType": "STRING"
                            }
                        },
                        {
                            "selector": "field_2",
                            "name": "Field 2",
                            "dataType": {
                                "basicType": "STRING"
                            }
                        }
                    ],
                    "providerFunction": "onMessageResourceFunction"
                }
            ]
        }
    }
}

Editar código

En el código de la aplicación:

1. Implementa providerFunction, llamado onMessageResourceFunction() en este ejemplo, que recupera contenido de recursos personalizados cuando es necesario. Toma la entrada e, que es la carga útil JSON del objeto de evento del paso, y, a partir de ella, establece el ID de recurso personalizado.

   Apps Script

   function onMessageResourceFunction(e) {
     var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
     var field_1 = ...;
     var field_2 = ...;
   
     return {
       "hostAppAction": {
         "workflowAction": {
           "resourceRetrievedAction": {
             "resourceJson": JSON.stringify({
               "field_1": field_1,
               "field_2": field_2,
             })
           }
         }
       }
     };
   }
   

2. La función del proveedor debe devolver el valor del recurso personalizado recuperándolo con un mecanismo adecuado, como llamar a una API o leer una base de datos.

3. Para recuperar y devolver un recurso personalizado por su ID, devuélvelo como returnOutputVariablesAction, como se muestra en onExecuteResourceFunction().

   Apps Script

   function onExecuteResourceFunction(e) {
     var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
     return {
       "hostAppAction": {
         "workflowAction": {
           "returnOutputVariablesAction": {
             "variableValues": [{
               "variableId": "resource_data",
               "variableData": {
                 "resourceReferences" : [ resource_id ]
               }
             }]
           }
         }
       }
     };
   }
   

Este es un ejemplo completo:

Apps Script

function onMessageResourceFunction(e) {
  var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
  var field_1 = ...;
  var field_2 = ...;

  return {
    "hostAppAction": {
      "workflowAction": {
        "resourceRetrievedAction": {
          "resourceJson": JSON.stringify({
            "field_1": field_1,
            "field_2": field_2,
          })
        }
      }
    }
  };
}

function onExecuteResourceFunction(e) {
  var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
  return {
    "hostAppAction": {
      "workflowAction": {
        "returnOutputVariablesAction": {
          "variableValues": [{
            "variableId": "resource_data",
            "variableData": {
              "resourceReferences" : [ resource_id ]
            }
          }]
        }
      }
    }
  };
}

Genera un recurso personalizado como valor

Cuando generas un recurso personalizado como referencia, lo devuelves por su ID en lugar del objeto de recurso personalizado completo. Si necesitas pasar el objeto de recurso completo, puedes hacerlo con resourceValues.

En resourceValues, defines el resultado de un paso.

Para generar un recurso personalizado como un valor, edita el archivo de manifiesto y el código del paso.

Edita el archivo de manifiesto

En el archivo de manifiesto, haz lo siguiente:

1. Especifica un workflowResourceDefinitions y asígnale un ID.El workflowResourceDefinitions es una estructura que define los tipos de datos y el contenido del recurso personalizado. Dentro de workflowResourceDefinitions, especificas los campos individuales que componen el recurso personalizado, en este ejemplo llamados field_1 y field_2.

2. Especifica un providerFunction cuyo valor sea el nombre de una función en el código del paso. El providerFunction recupera el contenido del recurso personalizado real cuando es necesario.

   JSON

   {
       "workflowResourceDefinitions": [
           {
               "id": "resource_id",
               "name": "Custom Resource",
               "fields": [
                   {
                       "selector": "field_1",
                       "name": "Field 1",
                       "dataType": {
                           "basicType": "STRING"
                       }
                   },
                   {
                       "selector": "field_2",
                       "name": "Field 2",
                       "dataType": {
                           "basicType": "STRING"
                       }
                   }
               ],
               "providerFunction": "onExecuteResourceAsValuesFunction"
           }
       ]
   }
   

3. En outputs[], especifica una variable de salida que devuelva resourceValues. El valor de cardinality debe ser SINGLE.

   JSON

   {
       "outputs": [
           {
               "id": "resource_data",
               "description": "Resource Data",
               "cardinality": "SINGLE",
               "dataType": {
                   "resourceValues": {
                       "value1": "value one"
                   }
               }
           }
       ]
   }
   

Este es un archivo de manifiesto completo que define un recurso personalizado:

JSON

{
    "timeZone": "America/Los_Angeles",
    "exceptionLogging": "STACKDRIVER",
    "runtimeVersion": "V8",
    "addOns": {
        "common": {
            "name": "Calculator",
            "logoUrl": "https://www.gstatic.com/images/branding/productlogos/calculator_search/v1/web-24dp/logo_calculator_search_color_1x_web_24dp.png",
            "useLocaleFromApp": true
        },
        "flows": {
            "workflowElements": [
                {
                    "id": "getResourceData",
                    "state": "ACTIVE",
                    "name": "Get Resource by ID",
                    "description": "Get Resource by ID",
                    "workflowAction": {
                        "outputs": [
                            {
                                "id": "resource_data",
                                "description": "Resource Data",
                                "cardinality": "SINGLE",
                                "dataType": {
                                    "resourceValues": {
                                        "value1": "value one"
                                    }
                                }
                            }
                        ],
                        "onConfigFunction": "onConfigResourceFunction",
                        "onExecuteFunction": "onExecuteResourceFunction"
                    }
                }
            ],
            "workflowResourceDefinitions": [
                {
                    "id": "resource_id",
                    "name": "Custom Resource",
                    "fields": [
                        {
                            "selector": "field_1",
                            "name": "Field 1",
                            "dataType": {
                                "basicType": "STRING"
                            }
                        },
                        {
                            "selector": "field_2",
                            "name": "Field 2",
                            "dataType": {
                                "basicType": "STRING"
                            }
                        }
                    ],
                    "providerFunction": "onExecuteResourceAsValuesFunction"
                }
            ]
        }
    }
}

Editar código

En el código de la aplicación, implementa providerFunction, llamado onExecuteResourceAsValuesFunction() en este ejemplo, que define y devuelve el recurso personalizado como JSON, aquí abstraído como resourceJSON:

Apps Script

function onExecuteResourceAsValuesFunction() {
  var field_1 = "value 1";
  var field_2 = "value 2";
  var resourceJSON = JSON.stringify({
    "field_1": field_1,
    "field_2": field_2,
  });
  return {
    "hostAppAction": {
      "workflowAction": {
        "returnOutputVariablesAction": {
          "variableValues": [{
            "variableId": "resource_data",
            "variableData": {
              "resourceValues" : [ resourceJSON ]
            }
          }]
        }
      }
    }
  };
}

Temas relacionados

• Variables de entrada
• Cómo validar una variable de entrada
• Variables de salida
• Registra la actividad y los errores
• Objeto de evento de flujo