Trang này được dịch bởi Cloud Translation API.

Bắt đầu nhanh: Xây dựng bước tính toán bằng Google Apps Script

Hướng dẫn bắt đầu nhanh này hướng dẫn bạn cách tạo một bước tuỳ chỉnh cho Workspace Studio bằng Google Apps Script. Bước tuỳ chỉnh này nhận hai số và một phép toán số học làm dữ liệu đầu vào, thực hiện phép tính và xuất kết quả.

Người dùng định cấu hình bước tính toán trong quy trình của một trợ lý.

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

Mục tiêu

Tạo một bước tuỳ chỉnh cho Workspace Studio bằng Google Apps Script.
Triển khai bước tuỳ chỉnh cho tổ chức Google Workspace của riêng bạn.
Kiểm thử bước tuỳ chỉnh trong Workspace Studio.

Điều kiện tiên quyết

Tài khoản Google có quyền truy cập vào Workspace Studio.

Thiết lập tập lệnh

Để thiết lập tập lệnh, hãy tạo một dự án Apps Script mới rồi kết nối dự án đó với dự án Cloud của bạn.

Nhấp vào nút sau để mở dự án Hướng dẫn nhanh về máy tính của Apps Script.

Mở dự án
Nhấp vào Tổng quan.
Trên trang tổng quan, hãy nhấp vào biểu tượng Tạo bản sao.
Đặt tên cho bản sao của dự án Apps Script:
1. Nhấp vào Bản sao của hướng dẫn nhanh về Máy tính.
2. Trong phần Tiêu đề dự án, hãy nhập Calculator quickstart.
3. Nhấp vào Đổi tên.

Không bắt buộc: Xem lại mã bắt đầu nhanh

Trong phần trước, bạn đã sao chép toàn bộ dự án Apps Script chứa tất cả mã ứng dụng cần thiết cho bước tuỳ chỉnh của tác nhân. Vì vậy, bạn không cần sao chép và dán từng tệp.

Bạn có thể xem lại từng tệp mà bạn đã sao chép trong phần trước tại đây (không bắt buộc):

appsscript.json

Tệp kê khai. Một tệp JSON đặc biệt chỉ định thông tin cơ bản về dự án mà Apps Script cần để chạy tập lệnh.

Xem mã `appsscript.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": "onConfigCalculateFunction",
            "onExecuteFunction": "onExecuteCalculateFunction"
          }
        }
      ]
    }
  }
}

Calculator.gs

Xác định một bước tuỳ chỉnh cho Google Workspace Studio. Bước này có tên là "Tính toán", nhận hai số và một phép toán làm dữ liệu đầu vào, đồng thời trả về kết quả của phép tính.

Xem mã `Calculator.gs`

/**
 * This script defines a custom step for Google Workspace Studio.
 * The step, named "Calculate", takes two numbers and an operation as input
 * and returns the result of the calculation.
 *
 * The script includes functions to:
 *
 * 1.  Define the configuration UI for the step using Card objects:
 *
 *     - `onConfigCalculateFunction()`: Generates the main configuration card.
 *     - Helper functions like `pushCard()`, `saveButton()` to build card components.
 *
 * 2.  Handle the execution of the step.
 *
 *     - `onExecuteCalculateFunction()`: Retrieves inputs, performs the calculation,
 *       and returns outputs.
 *
 * To learn more, see the following quickstart guide:
 * https://developers.google.com/workspace/add-ons/studio/quickstart
 */

/**
 * Creates an action response to push a new card onto the card stack.
 *
 * This function generates an action object that, when returned, causes the
 * provided card to be pushed onto the card stack, making it the currently
 * displayed card in the configuration UI.
 * @param {Object} card The Card object to push.
 * @return {Object} The action response object.
 */
function pushCard(card) {
  return {

      "action": {
        "navigations": [{
            "push_card": card
          }
        ]
      }  };  
}

/**
 * Creates an action response to update the currently displayed card.
 *
 * This function generates an action object that, when returned, causes the
 * currently displayed card to be replaced with the provided card in the
 * configuration UI.
 * @param {Object} card The Card object to update.
 * @return {Object} The render actions object.
 */
function updateCard(card) {
  return {
    "render_actions": {
      "action": {
        "navigations": [{
            "update_card": card
          }
        ]
      }
    }
  };
}

/**
 * Creates a button configuration object for saving the step.
 *
 * This function generates a button definition that, when clicked, triggers
 * a save action for the current step configuration.
 * @return {Object} The button widget object.
 */
function saveButton() {
  return {
      "text": "Save",
      "onClick": {
        "hostAppAction" : {
          "workflowAction" : {
            "saveWorkflowAction" : {}
          }
        }
      },
    };
}

/**
 * Creates a button configuration object for a refresh action.
 *
 * This function generates a button definition that, when clicked, triggers
 * a function to refresh the current card.
 * @param {string} functionName The name of the Apps Script function to call on click.
 * @return {Object} The button widget object.
 */
function refreshButton(functionName) {
  return {
      "text": "Refresh",
      "onClick": {
        "action" : {
          "function" : functionName
        }
      },
    };
}


/**
 * Generates and displays a configuration card for the sample calculation action.
 *
 * This function creates a card with input fields for two values and a dropdown
 * for selecting an arithmetic operation. The card also includes a "Save"
 * button to save the action configuration for the step.
 *
 * The input fields are configured to let the user select outputs from previous
 * steps as input values using the `hostAppDataSource` property.
 * This function is called when the user adds or edits the "Calculate" step in the UI.
 * @return {Object} The action response object containing the card to display.
 */
function onConfigCalculateFunction() {
  var card = {
    "sections": [
      {
        "header": "Action sample: 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 pushCard(card);
}

/**
 * Gets an integer value from variable data, handling both string and integer formats.
 *
 * This function attempts to extract an integer value from the provided variable data.
 * It checks if the data contains string values and, if so, parses the first string
 * as an integer. If integer values are present, it returns the first integer.
 * @param {Object} variableData The variable data object from the event.
 * @return {number} The extracted integer value.
 */
function getIntValue(variableData) {
  if (variableData.stringValues) {
    return parseInt(variableData.stringValues[0]);
  }
  return variableData.integerValues[0];
}

/**
* 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(variableDataMap) {
 const workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
   .setVariableDataMap(variableDataMap);

 const hostAppAction = AddOnsResponseService.newHostAppAction()
   .setWorkflowAction(workflowAction);

 const renderAction = AddOnsResponseService.newRenderActionBuilder()
   .setHostAppAction(hostAppAction)
   .build();

 return renderAction;
}

/**
 * Executes the calculation action based on the inputs from an event.
 *
 * This function retrieves input values ("value1", "value2") and the "operation"
 * from the event, performs the calculation, and returns the "result" and
 * "log" as output variables.
 * This function is called when the agent reaches this custom step.
 * @param {Object} event The event object passed by the runtime.
 * @return {Object} The output variables object.
 */
function onExecuteCalculateFunction(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;
 }

 const variableDataMap = { "result": AddOnsResponseService.newVariableData().addIntegerValue(calculatedValue) };

 return outputVariables(variableDataMap);
}

Triển khai và kiểm thử bước

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

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 này sẽ có sẵn ngay lập tức trong phần Agents (Nhân viên hỗ trợ). Bạn có thể cần làm mới Các tác nhân 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.
Mở phần Agents (Tác nhân).
Tạo một tác nhân bao gồm bước của bạn:
1. Nhấp vào Tác nhân mới.
2. Chọn cách bắt đầu tác nhân. Khi kiểm thử một bước, hãy chọn một điều kiện khởi động mà bạn có thể tự thiết lập, chẳng hạn như tự 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 đầu.
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. Đố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. Nhân viên hỗ trợ của bạn đã sẵn sàng hoạt động.
Chạy tác nhân bằng cách kích hoạt điều kiện khởi động của tác nhân. Ví dụ: nếu tác nhân của bạn bắt đầu khi bạn nhận được email, hãy gửi email cho chính mình.
Xác minh rằng nhân viên hỗ trợ chạy như dự kiến. 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 tác nhân. Để 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.

Các bước tiếp theo

Bạn đã tạo và kiểm thử thành công một bước tuỳ chỉnh cho Workspace Studio. Hiện bạn có thể:

Tiếp tục tuỳ chỉnh bước này bằng cách yêu cầu Gemini giúp bạn triển khai logic phức tạp hơn.
Tạo thẻ cấu hình để tuỳ chỉnh cấu hình bước.
Ghi lại hoạt động và lỗi để ghi lại và khắc phục sự cố khi chạy các bước.
Xem xét các đối tượng sự kiện để xem xét tải trọng JSON mà các tác nhân gửi và nhận khi các bước chạy.

Bắt đầu nhanh: Xây dựng bước tính toán bằng Google Apps Script Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.