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 Studio.

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. Khi đầu ra của một bước có cấu trúc tĩnh, hãy biểu thị đầu ra đó bằng một tài nguyên tuỳ chỉnh. Ví dụ: để tạo một khách hàng tiềm năng CRM, đầu ra của bạn cần có nhiều biến:

• Địa chỉ email
• Địa chỉ đường phố
• Tên

Để đảm bảo có tất cả dữ liệu cần thiết để tạo khách hàng tiềm năng CRM, hãy xuất một tài nguyên tuỳ chỉnh chứa địa chỉ email, địa chỉ đường phố và tên.

Xuất tài nguyên tuỳ chỉnh dưới dạng 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.

Để xuất một tài nguyên tuỳ chỉnh làm 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": "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"
        }
      ]
    }
  }
}

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) {
     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. 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, hãy trả về tài nguyên đó dưới dạng returnOutputVariablesAction, như minh hoạ trong 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();
   }
   

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

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

Chủ đề có liên quan

• Biến đầu vào
• Xác thực biến đầu vào
• Biến đầu ra
• Ghi nhật ký hoạt động và lỗi
• Đối tượng sự kiện của Workspace Studio