Komplexe Daten mit einer benutzerdefinierten Ressource darstellen

In dieser Anleitung wird beschrieben, wie Sie benutzerdefinierte Ressourcen für Google Workspace-Flows definieren.

Benutzerdefinierte Ressourcen sind benutzerdefinierte Datenstrukturen, die Sie definieren können, um mehrere Variablen zu gruppieren. Wenn Sie beispielsweise einen CRM-Lead erstellen möchten, übergeben Sie eine benutzerdefinierte Ressource mit einer E-Mail-Adresse, einer Adresse und einem Namen.

Es gibt zwei Möglichkeiten, benutzerdefinierte Ressourcen zu definieren:

  • Als Referenz:Wenn Sie eine benutzerdefinierte Ressource als Referenz ausgeben, geben Sie die benutzerdefinierte Ressource anhand ihrer ID anstelle des vollständigen benutzerdefinierten Ressourcenobjekts zurück. Dadurch wird die Leistung verbessert, da weniger Daten zwischen den Flow-Schritten übertragen werden. Wenn für Daten sekundäre Suchvorgänge erforderlich sind, ist es hilfreich, die ID zurückzugeben, um diese Suchvorgänge auszuführen.
  • Als Wert:Verwenden Sie diese Methode, wenn die Daten während der Ausführung abgerufen werden müssen oder wenn die benutzerdefinierte Ressource klein ist und keine vertraulichen Daten enthält.

Benutzerdefinierte Ressource als Referenz ausgeben

Wenn Sie eine benutzerdefinierte Ressource als Referenz ausgeben, können Sie die benutzerdefinierte Ressource anhand ihrer ID anstelle des vollständigen benutzerdefinierten Ressourcenobjekts zurückgeben. Wenn eine benutzerdefinierte Ressource groß oder komplex ist, wird die Leistung verbessert, wenn nur die ID übergeben wird, da so die Datenmenge reduziert wird, die zwischen den Ablaufschritten übertragen wird.

Wenn Sie eine benutzerdefinierte Ressource als Referenz ausgeben möchten, bearbeiten Sie die Manifestdatei und den Code des Schritts.

Manifestdatei bearbeiten

In der Manifestdatei:

  1. Geben Sie ein workflowResourceDefinitions an und weisen Sie ihm ein id, ein fields[]-Array und ein providerFunction zu. workflowResourceDefinitions ist eine Struktur, die Datentypen und Inhalte der benutzerdefinierten Ressource definiert.

  2. Im fields[]-Array geben Sie die einzelnen Felder an, aus denen die benutzerdefinierte Ressource besteht, in diesem Beispiel field_1 und field_2.

  3. Der Wert von providerFunction muss mit dem Namen einer Funktion im Code des Schritts übereinstimmen. Die providerFunction ruft bei Bedarf den tatsächlichen Inhalt der benutzerdefinierten Ressource ab.

    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. Geben Sie in outputs[] eine Ausgabevariable an, die einen dynamischen Satz von Ausgabevariablen zurückgibt. Die Ausgabevariable hat ein dataType mit dem Attribut resourceType. Der Wert von cardinality muss SINGLE sein.

    JSON

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

Hier ist eine vollständige Manifestdatei, in der eine benutzerdefinierte Ressource definiert wird:

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

Code bearbeiten

Im Anwendungscode:

  1. Implementieren Sie die providerFunction, die in diesem Beispiel onMessageResourceFunction() heißt und bei Bedarf benutzerdefinierte Ressourceninhalte abruft. Es wird die Eingabe e verwendet, die die JSON-Nutzlast des Ereignisobjekts des Schritts ist, und daraus wird die benutzerdefinierte Ressourcen-ID festgelegt.

    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. Die Anbieterfunktion muss den Wert der benutzerdefinierten Ressource zurückgeben, indem sie ihn mit einem geeigneten Mechanismus abruft, z. B. durch Aufrufen einer API oder Lesen einer Datenbank.

  3. Wenn Sie eine benutzerdefinierte Ressource anhand ihrer ID abrufen und zurückgeben möchten, geben Sie sie als returnOutputVariablesAction zurück, wie in onExecuteResourceFunction() gezeigt.

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

Hier ein vollständiges Beispiel:

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

Benutzerdefinierte Ressource als Wert ausgeben

Wenn Sie eine benutzerdefinierte Ressource als Referenz ausgeben, geben Sie die benutzerdefinierte Ressource anhand ihrer ID und nicht als vollständiges benutzerdefiniertes Ressourcenobjekt zurück. Wenn Sie das gesamte Ressourcenobjekt übergeben müssen, können Sie resourceValues verwenden.

In resourceValues definieren Sie die Ausgabe eines Schritts.

Wenn Sie eine benutzerdefinierte Ressource als Wert ausgeben möchten, bearbeiten Sie die Manifestdatei und den Code des Schritts.

Manifestdatei bearbeiten

In der Manifestdatei:

  1. Geben Sie ein workflowResourceDefinitions an und weisen Sie ihm eine ID zu.Das workflowResourceDefinitions ist eine Struktur, die Datentypen und Inhalte der benutzerdefinierten Ressource definiert. In workflowResourceDefinitions geben Sie die einzelnen Felder an, aus denen die benutzerdefinierte Ressource besteht, in diesem Beispiel field_1 und field_2.

  2. Geben Sie einen providerFunction an, dessen Wert der Name einer Funktion im Code des Schritts ist. Die providerFunction ruft bei Bedarf den tatsächlichen Inhalt der benutzerdefinierten Ressource ab.

    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. Geben Sie in outputs[] eine Ausgabevariable an, die resourceValues zurückgibt. Der Wert von cardinality muss SINGLE sein.

    JSON

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

Hier ist eine vollständige Manifestdatei, in der eine benutzerdefinierte Ressource definiert wird:

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

Code bearbeiten

Implementieren Sie im Anwendungscode die providerFunction, die in diesem Beispiel onExecuteResourceAsValuesFunction() heißt und die benutzerdefinierte Ressource als JSON definiert und zurückgibt. Hier wird sie als resourceJSON abstrahiert:

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