使用自訂資源表示複雜資料

本指南說明如何為 Google Workspace Studio 定義自訂資源。

自訂資源是您可定義的自訂資料結構，用於將多個變數分組。如果步驟的輸出內容具有靜態結構，請以自訂資源表示。舉例來說，如要建立 CRM 待開發客戶，輸出內容需要多個變數：

  • 電子郵件地址
  • 街道地址
  • 名稱

為確保所有必要資料都存在，以便建立 CRM 待開發客戶，請輸出包含電子郵件地址、街道地址和名稱的自訂資源。

輸出自訂資源做為參考

輸出自訂資源做為參照時，您可以依 ID 傳回自訂資源，而非完整的自訂資源物件。如果自訂資源很大或很複雜，只傳遞 ID 即可減少步驟間傳輸的資料量，進而提升效能。

如要輸出自訂資源做為參照，請編輯步驟的資訊清單檔案和程式碼。

編輯資訊清單檔案

在資訊清單檔案中：

  1. 指定 workflowResourceDefinitions，並指派 id、fields[] 陣列和 providerFunction。workflowResourceDefinitions 是一種結構，可定義自訂資源的資料類型和內容。

  2. 在 fields[] 陣列中，您會指定組成自訂資源的個別欄位，在本例中稱為 field_1 和 field_2。

  3. providerFunction 的值必須與步驟程式碼中的函式名稱相符。providerFunction 會在需要時擷取實際的自訂資源內容。

    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. 在 outputs[] 中，指定會傳回動態輸出變數集的輸出變數。輸出變數具有 dataType，且屬性為 resourceType。cardinality 的值必須為 SINGLE。

    JSON

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

以下是定義自訂資源的完整資訊清單檔案：

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

編輯程式碼

在應用程式程式碼中：

  1. 實作 providerFunction (在本範例中稱為 onMessageResourceFunction())，在需要時擷取自訂資源內容。這個函式會接收輸入的 e，也就是步驟的事件物件 JSON 酬載，並從中設定自訂資源 ID。

    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. 供應商函式必須透過適當機制 (例如呼叫 API 或讀取資料庫) 擷取自訂資源的值，然後傳回該值。

  3. 如要依 ID 擷取及傳回自訂資源，請以 returnOutputVariablesAction 形式傳回，如 onExecuteResourceFunction() 所示。

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

完整範例如下：

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