Rappresentare dati complessi con una risorsa personalizzata

Questa guida spiega come definire risorse personalizzate per Google Workspace Flows.

Le risorse personalizzate sono strutture di dati personalizzate che puoi definire per raggruppare più variabili. Ad esempio, per creare un lead CRM, passa una risorsa personalizzata contenente un indirizzo email, un indirizzo e un nome.

Questi sono i due modi per definire le risorse personalizzate:

  • Come riferimento:quando restituisci una risorsa personalizzata come riferimento, restituisci la risorsa personalizzata in base al suo ID anziché all'oggetto risorsa personalizzata completo. In questo modo le prestazioni migliorano riducendo i dati trasferiti tra i passaggi del flusso. Quando i dati richiedono ricerche secondarie, restituirne l'ID è utile per eseguirle.
  • Come valore: utilizza questo metodo quando i dati devono essere recuperati durante l'esecuzione o quando la risorsa personalizzata è piccola e non contiene dati sensibili.

Generare una risorsa personalizzata come riferimento

Se restituisci una risorsa personalizzata come riferimento, puoi restituire la risorsa personalizzata in base al suo ID anziché all'oggetto risorsa personalizzata completo. Se una risorsa personalizzata è grande o complessa, il passaggio del solo ID migliora le prestazioni riducendo i dati trasferiti tra i passaggi del flusso.

Per generare una risorsa personalizzata come riferimento, modifica il file manifest e il codice del passaggio.

Modificare il file manifest

Nel file manifest:

  1. Specifica un workflowResourceDefinitions e assegnagli un id, un array fields[] e un providerFunction. workflowResourceDefinitions è una struttura che definisce i tipi di dati e i contenuti della risorsa personalizzata.

  2. All'interno dell'array fields[], specifica i singoli campi che compongono la risorsa personalizzata, in questo esempio denominata field_1 e field_2.

  3. Il valore di providerFunction deve corrispondere al nome di una funzione nel codice del passaggio. providerFunction recupera i contenuti effettivi delle risorse personalizzate quando necessario.

    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. In outputs[], specifica una variabile di output che restituisce un insieme dinamico di variabili di output. La variabile di output ha un dataType con la proprietà resourceType. Il valore di cardinality deve essere SINGLE.

    JSON

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

Ecco un file manifest completo che definisce una risorsa personalizzata:

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"
                }
            ]
        }
    }
}

Modifica il codice

Nel codice dell'applicazione:

  1. Implementa providerFunction, denominato onMessageResourceFunction() in questo esempio, che recupera i contenuti delle risorse personalizzate quando necessario. Prende l'input e, ovvero il payload JSON dell'oggetto evento del passaggio, e imposta l'ID risorsa personalizzato.

    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 funzione del fornitore deve restituire il valore della risorsa personalizzata recuperandolo con un meccanismo appropriato, ad esempio chiamando un'API o leggendo un database.

  3. Per recuperare e restituire una risorsa personalizzata in base al suo ID, restituiscila come returnOutputVariablesAction, come mostrato in 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 ]
            }
          }]
        }
      }
    }
  };
}

Ecco un esempio 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 ]
            }
          }]
        }
      }
    }
  };
}

Restituisci una risorsa personalizzata come valore

Quando restituisci una risorsa personalizzata come riferimento, restituisci la risorsa personalizzata in base al suo ID anziché all'oggetto risorsa personalizzata completo. Se devi passare l'intero oggetto risorsa, puoi farlo con resourceValues.

In resourceValues, definisci l'output di un passaggio.

Per generare una risorsa personalizzata come valore, modifica il file manifest e il codice del passaggio.

Modificare il file manifest

Nel file manifest:

  1. Specifica un workflowResourceDefinitions e assegnagli un ID.Il workflowResourceDefinitions è una struttura che definisce i tipi di dati e i contenuti della risorsa personalizzata. All'interno di workflowResourceDefinitions, specifica i singoli campi che compongono la risorsa personalizzata, in questo esempio chiamati field_1 e field_2.

  2. Specifica un providerFunction il cui valore è il nome di una funzione nel codice del passaggio. providerFunction recupera i contenuti effettivi delle risorse personalizzate quando necessario.

    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. In outputs[], specifica una variabile di output che restituisce resourceValues. Il valore di cardinality deve essere SINGLE.

    JSON

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

Ecco un file manifest completo che definisce una risorsa personalizzata:

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"
                }
            ]
        }
    }
}

Modifica il codice

Nel codice dell'applicazione, implementa providerFunction, chiamato onExecuteResourceAsValuesFunction() in questo esempio, che definisce e restituisce la risorsa personalizzata come JSON, qui astratta come 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 ]
            }
          }]
        }
      }
    }
  };
}