Biểu thị dữ liệu phức tạp bằng tài nguyên tuỳ chỉnh

Hướng dẫn này giải thích cách xác định tài nguyên tuỳ chỉnh cho Google Workspace Flows.

Tài nguyên tuỳ chỉnh là cấu trúc dữ liệu tuỳ chỉnh mà bạn có thể xác định để nhóm nhiều biến với nhau. Ví dụ: để tạo một khách hàng tiềm năng CRM, hãy truyền một tài nguyên tuỳ chỉnh chứa địa chỉ email, địa chỉ đường phố và tên.

Đây là 2 cách để xác định tài nguyên tuỳ chỉnh:

  • Để tham khảo: Khi xuất một tài nguyên tuỳ chỉnh dưới dạng tài nguyên tham chiếu, bạn sẽ trả về tài nguyên tuỳ chỉnh theo mã nhận dạng thay vì toàn bộ đối tượng tài nguyên tuỳ chỉnh. Điều này giúp cải thiện hiệu suất bằng cách giảm lượng dữ liệu được chuyển giữa các bước trong quy trình. Khi dữ liệu yêu cầu các lượt tra cứu phụ, việc trả về mã nhận dạng của dữ liệu đó sẽ hữu ích cho việc thực hiện các lượt tra cứu đó.
  • Dưới dạng một giá trị: Sử dụng phương thức này khi dữ liệu phải được truy xuất trong quá trình thực thi hoặc khi tài nguyên tuỳ chỉnh có kích thước nhỏ và không chứa dữ liệu nhạy cảm.

Xuất tài nguyên tuỳ chỉnh dưới dạng một tài liệu tham khảo

Bằng cách xuất một tài nguyên tuỳ chỉnh dưới dạng một thông tin tham chiếu, bạn có thể trả về tài nguyên tuỳ chỉnh theo mã nhận dạng thay vì toàn bộ đối tượng tài nguyên tuỳ chỉnh. Nếu tài nguyên tuỳ chỉnh có kích thước lớn hoặc phức tạp, thì việc chỉ truyền mã nhận dạng sẽ cải thiện hiệu suất bằng cách giảm lượng dữ liệu được truyền giữa các bước trong quy trình.

Để xuất một tài nguyên tuỳ chỉnh dưới dạng thông tin tham chiếu, hãy chỉnh sửa tệp kê khai và mã của bước.

Chỉnh sửa tệp kê khai

Trong tệp kê khai:

  1. Chỉ định workflowResourceDefinitions và chỉ định id, mảng fields[] và providerFunction cho workflowResourceDefinitions. workflowResourceDefinitions là một cấu trúc xác định các loại dữ liệu và nội dung của tài nguyên tuỳ chỉnh.

  2. Trong mảng fields[], bạn chỉ định các trường riêng lẻ tạo nên tài nguyên tuỳ chỉnh, trong ví dụ này được gọi là field_1 và field_2.

  3. Giá trị của providerFunction phải khớp với tên của một hàm trong mã của bước. providerFunction truy xuất nội dung tài nguyên tuỳ chỉnh thực tế khi cần.

    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. Trong outputs[], hãy chỉ định một biến đầu ra trả về một tập hợp biến đầu ra động. Biến đầu ra có một dataType với thuộc tính resourceType. Giá trị của cardinality phải là SINGLE.

    JSON

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

Sau đây là một tệp kê khai hoàn chỉnh xác định một tài nguyên tuỳ chỉnh:

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

Chỉnh sửa đoạn mã

Trong mã ứng dụng:

  1. Triển khai providerFunction (được gọi là onMessageResourceFunction() trong ví dụ này), truy xuất nội dung tài nguyên tuỳ chỉnh khi cần. Thao tác này lấy dữ liệu đầu vào e là tải trọng JSON của đối tượng sự kiện của bước và đặt mã tài nguyên tuỳ chỉnh từ đó.

    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. Hàm nhà cung cấp phải trả về giá trị của tài nguyên tuỳ chỉnh bằng cách truy xuất giá trị đó bằng một cơ chế thích hợp, chẳng hạn như gọi một API hoặc đọc một cơ sở dữ liệu.

  3. Để truy xuất và trả về một tài nguyên tuỳ chỉnh theo mã nhận dạng của tài nguyên đó, hãy trả về tài nguyên đó dưới dạng returnOutputVariablesAction, như minh hoạ trong 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 ]
            }
          }]
        }
      }
    }
  };
}

Sau đây là một ví dụ hoàn chỉnh:

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

Xuất một tài nguyên tuỳ chỉnh dưới dạng giá trị

Khi xuất một tài nguyên tuỳ chỉnh dưới dạng một tài nguyên tham chiếu, bạn sẽ trả về tài nguyên tuỳ chỉnh theo mã nhận dạng thay vì toàn bộ đối tượng tài nguyên tuỳ chỉnh. Nếu cần truyền toàn bộ đối tượng tài nguyên, bạn có thể dùng resourceValues.

Trong resourceValues, bạn xác định đầu ra của một bước.

Để xuất một tài nguyên tuỳ chỉnh dưới dạng giá trị, hãy chỉnh sửa tệp kê khai và mã của bước.

Chỉnh sửa tệp kê khai

Trong tệp kê khai:

  1. Chỉ định một workflowResourceDefinitions và chỉ định mã nhận dạng cho workflowResourceDefinitions đó.workflowResourceDefinitions là một cấu trúc xác định các loại dữ liệu và nội dung của tài nguyên tuỳ chỉnh. Trong workflowResourceDefinitions, bạn chỉ định các trường riêng lẻ tạo nên tài nguyên tuỳ chỉnh, trong ví dụ này được gọi là field_1 và field_2.

  2. Chỉ định một providerFunction có giá trị là tên của một hàm trong mã của bước. providerFunction truy xuất nội dung tài nguyên tuỳ chỉnh thực tế khi cần.

    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. Trong outputs[], hãy chỉ định một biến đầu ra trả về resourceValues. Giá trị của cardinality phải là SINGLE.

    JSON

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

Sau đây là một tệp kê khai hoàn chỉnh xác định một tài nguyên tuỳ chỉnh:

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

Chỉnh sửa đoạn mã

Trong mã ứng dụng, hãy triển khai providerFunction, được gọi là onExecuteResourceAsValuesFunction() trong ví dụ này, xác định và trả về tài nguyên tuỳ chỉnh dưới dạng JSON, ở đây được trừu tượng hoá dưới dạng 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 ]
            }
          }]
        }
      }
    }
  };
}