Représenter des données complexes avec une ressource personnalisée

Ce guide explique comment définir des ressources personnalisées pour Google Workspace Flows.

Les ressources personnalisées sont des structures de données personnalisées que vous pouvez définir pour regrouper plusieurs variables. Par exemple, pour créer un prospect CRM, transmettez une ressource personnalisée contenant une adresse e-mail, une adresse postale et un nom.

Voici les deux façons de définir des ressources personnalisées :

  • En tant que référence : lorsque vous générez une ressource personnalisée en tant que référence, vous renvoyez la ressource personnalisée par son ID au lieu de l'objet de ressource personnalisée complet. Cela améliore les performances en réduisant les données transférées entre les étapes du flux. Lorsque les données nécessitent des recherches secondaires, il est utile de renvoyer leur ID pour effectuer ces recherches.
  • En tant que valeur : utilisez cette méthode lorsque les données doivent être récupérées lors de l'exécution ou lorsque la ressource personnalisée est petite et ne contient pas de données sensibles.

Afficher une ressource personnalisée comme référence

En générant une ressource personnalisée en tant que référence, vous pouvez renvoyer la ressource personnalisée par son ID au lieu de l'objet de ressource personnalisée complet. Si une ressource personnalisée est volumineuse ou complexe, le fait de ne transmettre que l'ID améliore les performances en réduisant les données transférées entre les étapes du flux.

Pour générer une ressource personnalisée en tant que référence, modifiez le fichier manifeste et le code de l'étape.

Modifier le fichier manifeste

Dans le fichier manifeste :

  1. Spécifiez un workflowResourceDefinitions et attribuez-lui un id, un tableau fields[] et un providerFunction. workflowResourceDefinitions est une structure qui définit les types de données et le contenu de la ressource personnalisée.

  2. Dans le tableau fields[], vous spécifiez les champs individuels qui composent la ressource personnalisée, appelés field_1 et field_2 dans cet exemple.

  3. La valeur de providerFunction doit correspondre au nom d'une fonction dans le code de l'étape. providerFunction récupère le contenu réel de la ressource personnalisée si nécessaire.

    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. Dans outputs[], spécifiez une variable de sortie qui renvoie un ensemble dynamique de variables de sortie. La variable de sortie possède un dataType avec la propriété resourceType. La valeur de cardinality doit être SINGLE.

    JSON

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

Voici un fichier manifeste complet qui définit une ressource personnalisée :

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

Modifier le code

Dans le code de l'application :

  1. Implémentez providerFunction, appelé onMessageResourceFunction() dans cet exemple, qui récupère le contenu de la ressource personnalisée si nécessaire. Il prend l'entrée e, qui correspond à la charge utile JSON de l'objet d'événement de l'étape, et définit l'ID de ressource personnalisé à partir de celle-ci.

    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 fonction de fournisseur doit renvoyer la valeur de la ressource personnalisée en la récupérant avec un mécanisme approprié, comme l'appel d'une API ou la lecture d'une base de données.

  3. Pour récupérer et renvoyer une ressource personnalisée par son ID, renvoyez-la en tant que returnOutputVariablesAction, comme indiqué dans 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 ]
            }
          }]
        }
      }
    }
  };
}

Voici un exemple complet :

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

Générer une ressource personnalisée en tant que valeur

Lorsque vous générez une ressource personnalisée en tant que référence, vous renvoyez la ressource personnalisée par son ID au lieu de l'objet de ressource personnalisée complet. Si vous devez transmettre l'intégralité de l'objet de ressource, vous pouvez le faire avec resourceValues.

Dans resourceValues, vous définissez la sortie d'une étape.

Pour générer une ressource personnalisée en tant que valeur, modifiez le fichier manifeste et le code de l'étape.

Modifier le fichier manifeste

Dans le fichier manifeste :

  1. Spécifiez un workflowResourceDefinitions et attribuez-lui un ID.Le workflowResourceDefinitions est une structure qui définit les types de données et le contenu de la ressource personnalisée. Dans workflowResourceDefinitions, vous spécifiez les champs individuels qui composent la ressource personnalisée, appelés field_1 et field_2 dans cet exemple.

  2. Spécifiez un providerFunction dont la valeur est le nom d'une fonction dans le code de l'étape. providerFunction récupère le contenu réel de la ressource personnalisée si nécessaire.

    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. Dans outputs[], spécifiez une variable de sortie qui renvoie resourceValues. La valeur de cardinality doit être SINGLE.

    JSON

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

Voici un fichier manifeste complet qui définit une ressource personnalisée :

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

Modifier le code

Dans le code de l'application, implémentez providerFunction, appelé onExecuteResourceAsValuesFunction() dans cet exemple, qui définit et renvoie la ressource personnalisée au format JSON, ici abstraite sous la forme 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 ]
            }
          }]
        }
      }
    }
  };
}