Komplexe Daten mit einer benutzerdefinierten Ressource darstellen

In dieser Anleitung wird erläutert, wie Sie benutzerdefinierte Ressourcen für Google Workspace Studio definieren.

Benutzerdefinierte Ressourcen sind benutzerdefinierte Datenstrukturen, mit denen Sie mehrere Variablen gruppieren können. Wenn die Ausgabe eines Schritts eine statische Struktur hat, stellen Sie sie mit einer benutzerdefinierten Ressource dar. Wenn Sie beispielsweise einen CRM-Lead erstellen möchten, sind für die Ausgabe mehrere Variablen erforderlich:

  • E-Mail-Adresse
  • Adresse
  • Name

Um sicherzustellen, dass alle Daten vorhanden sind, die zum Erstellen eines CRM-Leads erforderlich sind, geben Sie eine benutzerdefinierte Ressource aus, die eine E-Mail-Adresse, eine Adresse und einen Namen 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, verbessert das Übergeben nur der ID die Leistung, da die zwischen den Schritten übertragenen Daten reduziert werden.

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 workflowResourceDefinitions an und weisen Sie ihr eine id, ein fields[] Array und eine 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 eine dynamische Menge von Ausgabevariablen zurückgibt. Die Ausgabevariable hat einen dataType mit der Eigenschaft 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, die eine benutzerdefinierte Ressource definiert:

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Custom Resource (as reference)",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "getResourceDataReference",
          "state": "ACTIVE",
          "name": "Custom Resource (as reference)",
          "description": "Output a custom resource as a reference",
          "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, in diesem Beispiel onMessageResourceFunction, die bei Bedarf den Inhalt der benutzerdefinierten Ressource abruft. Sie verwendet die Eingabe e, die die JSON-Nutzlast des Ereignisobjekts des Schritts ist, und legt daraus die ID der benutzerdefinierten Ressource fest.

    Apps Script

    function onMessageResourceFunction(e) {
  console.log("Payload in onMessageResourceFunction: " + JSON.stringify(e));

  var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
  let fieldValue_1;
  let fieldValue_2;

  // Using an if condition to mock a database call.
  if (resource_id == "sample_resource_reference_id") {
    fieldValue_1 = AddOnsResponseService.newVariableData()
      .addStringValue("value1");
    fieldValue_2 = AddOnsResponseService.newVariableData()
      .addStringValue("value2");
  } else {
    fieldValue_1 = AddOnsResponseService.newVariableData()
      .addStringValue("field_1 value not found");
    fieldValue_2 = AddOnsResponseService.newVariableData()
      .addStringValue("field_2 value not found");
  }

  let resourceData = AddOnsResponseService.newResourceData()
    .addVariableData("field_1", fieldValue_1)
    .addVariableData("field_2", fieldValue_2)

  let workflowAction = AddOnsResponseService.newResourceRetrievedAction()
    .setResourceData(resourceData)

  let hostAppAction = AddOnsResponseService.newHostAppAction()
    .setWorkflowAction(workflowAction);

  return AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();
}

  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) {
  console.log("Payload in onExecuteResourceFunction: " + JSON.stringify(e));

  let outputVariables = AddOnsResponseService.newVariableData()
    .addResourceReference("sample_resource_reference_id");

  let workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
    .addVariableData("resource_data", outputVariables);

  let hostAppAction = AddOnsResponseService.newHostAppAction()
    .setWorkflowAction(workflowAction);

  return AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();
}

Hier ist ein vollständiges Beispiel:

Apps Script

function onConfigResourceFunction() {
  let section = CardService.newCardSection()
    .addWidget(
      CardService.newTextParagraph()
        .setText("This is the Custom Resource Demo card")
    );

  const card = CardService.newCardBuilder()
    .addSection(section)
    .build();

  return card;
}

function onMessageResourceFunction(e) {
  console.log("Payload in onMessageResourceFunction: " + JSON.stringify(e));

  var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
  let fieldValue_1;
  let fieldValue_2;

  // Using an if condition to mock a database call.
  if (resource_id == "sample_resource_reference_id") {
    fieldValue_1 = AddOnsResponseService.newVariableData()
      .addStringValue("value1");
    fieldValue_2 = AddOnsResponseService.newVariableData()
      .addStringValue("value2");
  } else {
    fieldValue_1 = AddOnsResponseService.newVariableData()
      .addStringValue("field_1 value not found");
    fieldValue_2 = AddOnsResponseService.newVariableData()
      .addStringValue("field_2 value not found");
  }

  let resourceData = AddOnsResponseService.newResourceData()
    .addVariableData("field_1", fieldValue_1)
    .addVariableData("field_2", fieldValue_2)

  let workflowAction = AddOnsResponseService.newResourceRetrievedAction()
    .setResourceData(resourceData)

  let hostAppAction = AddOnsResponseService.newHostAppAction()
    .setWorkflowAction(workflowAction);

  return AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();
}

function onExecuteResourceFunction(e) {
  console.log("Payload in onExecuteResourceFunction: " + JSON.stringify(e));

  let outputVariables = AddOnsResponseService.newVariableData()
    .addResourceReference("sample_resource_reference_id");

  let workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
    .addVariableData("resource_data", outputVariables);

  let hostAppAction = AddOnsResponseService.newHostAppAction()
    .setWorkflowAction(workflowAction);

  return AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();
}