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

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

自訂資源是您定義的自訂資料結構，可將多個變數分組。舉例來說，如要建立 CRM 待開發客戶，請傳遞包含電子郵件地址、街道地址和名稱的自訂資源。

定義自訂資源的方式有兩種：

  • 做為參照：將自訂資源輸出為參照時，您會依 ID 傳回自訂資源，而不是完整的自訂資源物件。藉此減少流程步驟之間傳輸的資料量，進而提升效能。如果資料需要二次查詢，傳回 ID 有助於執行這些查詢。
  • 做為值：如果資料必須在執行期間擷取，或自訂資源較小且不含私密資料，請使用這個方法。

輸出自訂資源做為參考

輸出自訂資源做為參照時，您可以透過 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": "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"
                }
            ]
        }
    }
}

編輯程式碼

在應用程式程式碼中：

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

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

  3. 如要依 ID 擷取及傳回自訂資源，請以 returnOutputVariablesAction 形式傳回，如 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 ]
            }
          }]
        }
      }
    }
  };
}

以下是完整範例：

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

將自訂資源輸出為值

將自訂資源輸出為參照時，您會依 ID 傳回自訂資源，而不是完整的自訂資源物件。如要傳遞整個資源物件，可以使用 resourceValues。

在 resourceValues 中，您可以定義步驟的輸出內容。

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

編輯資訊清單檔案

在資訊清單檔案中：

  1. 指定 workflowResourceDefinitions 並指派 ID。workflowResourceDefinitions 是一種結構，可定義自訂資源的資料類型和內容。在 workflowResourceDefinitions 中，您會指定組成自訂資源的個別欄位，在本範例中稱為 field_1 和 field_2。

  2. 指定 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": "onExecuteResourceAsValuesFunction"
        }
    ]
}

  3. 在 outputs[] 中，指定會傳回 resourceValues 的輸出變數。 cardinality 的值必須為 SINGLE。

    JSON

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

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

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

編輯程式碼

在應用程式程式碼中，實作 providerFunction (本例中稱為 onExecuteResourceAsValuesFunction())，定義並以 JSON 形式傳回自訂資源，在此抽象化為 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 ]
            }
          }]
        }
      }
    }
  };
}