Komplexe Daten mit einer benutzerdefinierten Ressource darstellen

In diesem Leitfaden wird beschrieben, wie Sie benutzerdefinierte Ressourcen für Google Workspace Studio definieren.

Benutzerdefinierte Ressourcen sind benutzerdefinierte Datenstrukturen, die Sie definieren können, um mehrere Variablen zu gruppieren. 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, benötigen Sie in der Ausgabe mehrere Variablen:

  • 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 mit einer E-Mail-Adresse, einer Anschrift und einem Namen aus.

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 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 ein workflowResourceDefinitions an und weisen Sie ihm ein id, ein fields[]-Array und ein providerFunction zu. Die workflowResourceDefinitions ist eine Struktur, die Datentypen und Inhalte der benutzerdefinierten Ressource definiert.

  2. Im Array fields[] 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": "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, 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) {
  console.log("Payload in onMessageResourceFunction: " + JSON.stringify(e));

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

  // Using a 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 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 a 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();
}