Xây dựng một bước

Chương trình Gemini Alpha: Flows có trong chương trình Gemini Alpha.

Hướng dẫn này giải thích cách tạo một bước mà người dùng có thể thêm vào quy trình trong Google Workspace Flows.

Bước là một bước duy nhất trong chuỗi tác vụ của một quy trình. Các bước không thể bắt đầu một quy trình.

Ví dụ: hãy xem xét một bước thực hiện phép tính số học. Chương trình này yêu cầu người dùng nhập hai giá trị và một phép toán. Sau đó, hàm này thực hiện phép toán trên các giá trị và xuất kết quả.

Hình 1: Người dùng định cấu hình bước máy tính trong một luồng.

Để tạo một bước, hãy định cấu hình bước đó trong tệp kê khai của tiện ích bổ sung, viết logic ứng dụng trong mã của tiện ích bổ sung Google Workspace, đồng thời triển khai và kiểm thử bước đó. Trong giai đoạn thử nghiệm alpha, đừng xuất bản một tiện ích bổ sung mở rộng Flows.

Xác định bước

Để định cấu hình một bước, hãy xác định bước đó trong tệp kê khai và viết logic ứng dụng của bước đó trong mã.

Xác định bước trong tệp kê khai

Trong tệp kê khai, appsscript.json:

1. Đặt onConfigFunction và onExecuteFunction thành tên của các hàm tương ứng trong mã của tiện ích bổ sung. Trong ví dụ này, các hàm được gọi là onConfigCalculate() và onExecuteCalculate().
   • onConfigFunction thiết lập và định cấu hình bước này. Nếu cần, hãy thu thập dữ liệu từ người dùng cần thiết để thực hiện bước này, chẳng hạn như địa chỉ để gửi email. Trong ví dụ của hướng dẫn này, chúng ta yêu cầu 2 giá trị và một phép toán.
   • onExecuteFunction thực thi bước này. Nếu dữ liệu được thu thập từ người dùng, thì dữ liệu đó sẽ được chuyển đến hàm này. Nếu có, hàm này sẽ trả về một đầu ra. Trong ví dụ của hướng dẫn này, kết quả của một phép tính toán sẽ được xuất ra.

2. Đặt các đầu vào và đầu ra bắt buộc để bước này thu thập dữ liệu và gửi dữ liệu đó đến các bước sau. Trong ví dụ này, hãy yêu cầu người dùng nhập hai giá trị và một phép toán học được xác định trong inputs[]. Xuất kết quả đã tính theo định nghĩa trong outputs[].

   Để tìm hiểu thêm về đầu vào và đầu ra, hãy xem phần Biến đầu vào và Biến đầu ra. Để đảm bảo các luồng chạy mà không gặp lỗi, hãy xác thực các biến đầu vào.

Dưới đây là tệp kê khai cho bước Máy tí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": "actionElement",
          "state": "ACTIVE",
          "name": "Calculate",
          "description": "Asks the user for two values and a math operation, then performs the math operation on the values and outputs the result.",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "value1",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "value2",
                "description": "value2",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "operation",
                "description": "operation",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "outputs": [
              {
                "id": "result",
                "description": "Calculated result",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              }
            ],
            "onConfigFunction": "onConfigCalculate",
            "onExecuteFunction": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

Tiếp theo, hãy viết mã hỗ trợ bằng cách xác định bước trong mã.

Xác định bước trong mã

Trong mã ứng dụng, hãy làm như sau:

1. Viết onConfigFunction, được gọi là onConfigCalculate() trong ví dụ này. Khi thêm bước này vào một quy trình, người dùng có thể định cấu hình các khía cạnh của bước đó trong trình tạo quy trình. Để thu thập thông tin bắt buộc từ người dùng, onConfigFunction sẽ xác định một thẻ cấu hình.

   Thẻ là các khối xây dựng cho giao diện người dùng trong các tiện ích bổ sung. Thẻ hỗ trợ một bố cục xác định, các phần tử tương tác trên giao diện người dùng (như nút) và nội dung đa phương tiện (như hình ảnh). Thẻ là cách bạn có thể lấy dữ liệu từ người dùng mà bước này cần chạy, chẳng hạn như địa chỉ email để gửi email.

   OnConfigFunction trả về một đối tượng RenderActions chứa một thẻ. Thẻ này xác định giao diện người dùng nơi người dùng đặt dữ liệu của bước. Trong ví dụ này, onConfigFunction tạo một thẻ yêu cầu người dùng nhập hai giá trị và một phép toán.

2. Viết onExecuteFunction có tên là onExecuteCalculate() trong ví dụ này. Khi bước của bạn chạy trong một quy trình, OnExecuteFunction sẽ chạy. Mọi giá trị đầu vào mà người dùng đặt trong quá trình định cấu hình như được xác định trong onConfigurationFunction đều được truyền đến OnExecuteFunction.

   Viết OnExecuteFunction() để hàm này thực thi đồng bộ tác vụ bằng cách sử dụng dữ liệu đầu vào được cung cấp. Hãy nhớ rằng OnExecuteFunction() phải trả về tất cả các đầu ra được xác định trong tệp kê khai của quy trình, nếu không sẽ xảy ra lỗi.

Mẫu mã này bao gồm một hàm hỗ trợ, outputVariables(), hàm này tạo và gửi các biến được cung cấp dưới dạng đầu ra từ bước.

Bước của bạn đã sẵn sàng để kiểm thử.

Dưới đây là mã cho bước Máy tính:

Apps Script

/**
 * Generates and displays a configuration card for the sample calculation step.
 *
 * This function creates a card with input fields for two values and a drop-down
 * for selecting an arithmetic operation. The card also includes a "Save"
 * button to save the step configuration for the workflow.
 *
 * The input fields are configured to let the user select outputs from previous
 * workflow steps as input values using the `hostAppDataSource` property.
 */
function onConfigCalculate() {
  var card = {
    "sections": [
      {
        "header": "Step example: Calculate",
        "widgets": [
          {
            "textInput": {
              "name": "value1",
              "label": "First value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          },
          {
            "selectionInput": {
              "name": "operation",
              "label": "Operation",
              "type": "DROPDOWN",
              "items": [
                {
                  "text": "+",
                  "value": "+",
                },
                {
                  "text": "-",
                  "value": "-",
                },
                {
                  "text": "x",
                  "value": "x",
                },
                {
                  "text": "/",
                  "value": "/",
                }
              ]
            }
          },
          {
            "textInput": {
              "name": "value2",
              "label": "Second value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

/**
 * Returns output variables from a step.
 *
 * This function constructs an object that, when returned, sends the
 * provided variable values as output from the current step.
 * The variable values are logged to the console for debugging purposes.
 */
function outputVariables(variableValues) {
  var renderAction =  {
    "hostAppAction" : {
      "workflowAction" : {
        "returnOutputVariablesAction" : {
          "variables" : variableValues
        }
      }
    }
  };
  console.log("renderAction: " + JSON.stringify(renderAction));
  return renderAction;
}

/**
 * Executes the calculation step based on the inputs from a flow event.
 *
 * This function retrieves input values and the operation from the flow event,
 * performs the calculation, and returns the result as an output variable.
 * The function logs the event for debugging purposes.
 */
function onExecuteCalculate(event) {
  console.log("output: " + JSON.stringify(event));
  var calculatedValue = 0;
  var value1 = event.workflow.actionInvocation.inputs["value1"].integerValues[0];
  var value2 = event.workflow.actionInvocation.inputs["value2"].integerValues[0];
  var operation = event.workflow.actionInvocation.inputs["operation"].stringValues[0];

  if (operation == "+") {
    calculatedValue = value1 + value2;
  } else if (operation == "-") {
    calculatedValue = value1 - value2;
  } else if (operation == "x") {
    calculatedValue = value1 * value2;
  } else if (operation == "/") {
    calculatedValue = value1 / value2;
  }
  return outputVariables([{
    "variableId": "result",
    "variableData": {
        "integerValues": [
          calculatedValue
        ]
      },
  }]);
}

Kiểm tra bước của bạn

Để kiểm thử bước này, hãy thiết lập một bản triển khai kiểm thử cho tiện ích bổ sung, thêm bước này vào một quy trình rồi chạy quy trình đó.

1. Thiết lập một bản triển khai thử nghiệm cho tiện ích bổ sung:

   1. Mở dự án tập lệnh trong trình chỉnh sửa Apps Script.
   2. Nhấp vào Triển khai > Kiểm thử việc triển khai.
   3. Nhấp vào Install (Cài đặt).
   4. Ở dưới cùng, hãy nhấp vào Xong.

   Bạn có thể cho phép người dùng khác kiểm thử tiện ích bổ sung bằng cách chia sẻ dự án Apps Script với tài khoản của họ (cần có quyền chỉnh sửa). Sau đó, nhắc người dùng làm theo các bước trước đó.

   Sau khi cài đặt, tiện ích bổ sung sẽ có sẵn ngay lập tức trong Flows. Bạn có thể cần làm mới Flows trước khi tiện ích bổ sung xuất hiện. Bạn cũng phải uỷ quyền cho tiện ích bổ sung trước khi sử dụng.

   Để tìm hiểu thêm về việc triển khai thử nghiệm, hãy xem bài viết Cài đặt tiện ích bổ sung chưa xuất bản.

2. Mở Flows.

3. Tạo một quy trình bao gồm bước của bạn:

   1. Nhấp vào Luồng mới.
   2. Chọn cách bắt đầu quy trình. Khi kiểm thử một bước, bạn nên chọn một sự kiện bắt đầu mà bạn có thể tự kích hoạt, chẳng hạn như gửi email cho chính mình. Nếu bước của bạn yêu cầu một biến đầu vào, hãy định cấu hình biến đầu vào trong phần đầu ra của bước khởi động.
   3. Nhấp vào Thêm bước. Chọn bước mà bạn đã tạo hoặc cập nhật, có tên là Tính toán.
   4. Định cấu hình bước của bạn. Đối với bước tính toán, hãy chọn hai giá trị và một phép toán. Bước này sẽ tự động lưu.
   5. Để kiểm thử đầu ra của bước, hãy thêm một bước khác. Ví dụ: để thêm đầu ra vào một thư email, bạn có thể thêm bước Gửi thư của Gmail. Trong Message (Thông báo), hãy nhấp vào Variables (Biến) rồi chọn đầu ra của bước. Đối với bước tính toán, hãy chọn Variables (Biến) > Step 2: Calculated result (Bước 2: Kết quả được tính) > Calculated result (Kết quả được tính). Biến này xuất hiện dưới dạng một khối trong trường Tin nhắn.
   6. Nhấp vào Bật. Luồng của bạn đã sẵn sàng chạy.

4. Chạy quy trình bằng cách kích hoạt điều kiện khởi động của quy trình. Ví dụ: nếu quy trình của bạn bắt đầu khi bạn nhận được email, hãy gửi email cho chính mình.

5. Xác minh xem luồng có chạy như dự kiến hay không. Kiểm tra nhật ký bằng cách truy cập vào thẻ Hoạt động của trình tạo quy trình. Để tìm hiểu cách tạo nhật ký tuỳ chỉnh trong thẻ Hoạt động, hãy xem phần Nhật ký hoạt động.

Chủ đề có liên quan

• Biến đầu vào
• Xác thực biến đầu vào
• Biến đầu ra
• Xác định tài nguyên tuỳ chỉnh
• Biến động
• Ghi nhật ký hoạt động và lỗi
• Đối tượng sự kiện Flows