建構步驟

本指南說明如何建立使用者可新增至 Google Workspace Studio 代理程式的步驟。

步驟是代理程式一系列工作中的單一步驟。步驟無法啟動代理程式。

舉例來說，假設某個步驟會執行算術運算。這項函式會要求使用者提供兩個值和一項數學運算。然後對這些值執行數學運算，並輸出結果。

圖 1：使用者將計算機步驟設定為代理程式的一部分。

如要建構步驟，請在外掛程式的資訊清單檔案中設定步驟，在 Google Workspace 外掛程式的程式碼中編寫應用程式邏輯，然後部署及測試步驟。

定義步驟

如要設定步驟，請在資訊清單檔案中定義步驟，並在程式碼中編寫應用程式邏輯。

在資訊清單檔案中定義步驟

在資訊清單檔案中，appsscript.json：

1. 將 onConfigFunction 和 onExecuteFunction 設為外掛程式碼中對應函式的名稱。在本範例中，函式稱為 onConfigCalculate() 和 onExecuteCalculate()。
   • onConfigFunction 會設定及設定步驟。如有必要，請向使用者收集執行步驟所需的資料，例如傳送電子郵件的地址。在本指南的範例中，我們會要求提供兩個值和一項數學運算。
   • onExecuteFunction 會執行該步驟。如果資料是從使用者收集而來，該資料會傳遞至這個函式。如果適用，則會傳回輸出內容。在本指南的範例中，輸出數學計算結果。

2. 設定必要輸入和輸出內容，讓步驟收集資料並傳送至後續步驟。在本範例中，請向使用者索取兩個值，以及 inputs[] 中定義的數學運算。根據 outputs[] 輸出計算結果。

   如要進一步瞭解輸入和輸出內容，請參閱輸入變數和輸出變數。為確保代理程式正常運作，請驗證輸入變數。

以下是「計算機」步驟的資訊清單檔案：

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

接著，請在程式碼中定義步驟，編寫支援程式碼。

在程式碼中定義步驟

在應用程式程式碼中，請執行下列操作：

1. 編寫 onConfigFunction，在本例中稱為 onConfigCalculate()。 使用者將步驟新增至代理程式後，即可在代理程式建構工具中設定步驟的各個層面。如要向使用者收集必要資訊，onConfigFunction 會定義設定卡片。

   資訊卡是外掛程式使用者介面的建構元素。資訊卡支援已定義的版面配置、按鈕等互動式 UI 元素，以及圖片等豐富媒體。您可以使用資訊卡從使用者取得步驟執行所需的資料，例如傳送電子郵件時所需的電子郵件地址。

   OnConfigFunction 會傳回一張卡片。這張卡片定義了使用者設定步驟資料的 UI。在本例中，onConfigFunction 會建構一張資訊卡，要求使用者提供兩個值和數學運算。

2. 在本範例中，請編寫名為 onExecuteCalculate() 的 onExecuteFunction。當步驟在代理程式中執行時，系統會執行 OnExecuteFunction。使用者在設定期間設定的任何輸入值 (如 onConfigurationFunction 中所定義)，都會傳遞至 OnExecuteFunction。

   請編寫 OnExecuteFunction()，以便使用提供的輸入內容同步執行工作。請注意，OnExecuteFunction() 必須傳回代理程式資訊清單中定義的所有輸出內容，否則會發生錯誤。

這個程式碼範例包含支援函式 outputVariables()，可建構並傳送提供的變數做為步驟的輸出內容。

您的步驟已可供測試。

以下是「計算機」步驟的程式碼：

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 input fields are configured to let the user select outputs from previous
 * steps as input values using the `hostAppDataSource` property.
 */
function onConfigCalculate() {
  const firstInput = CardService.newTextInput()
  .setFieldName("value1")
  .setTitle("First Value")
  .setHostAppDataSource(
    CardService.newHostAppDataSource()
      .setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
      )
  );
  const secondInput = CardService.newTextInput()
    .setFieldName("value2")
    .setTitle("Second Value").setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );
  const selectionInput = CardService.newSelectionInput()
    .setTitle("operation")
    .setFieldName("operation")
    .setType(CardService.SelectionInputType.DROPDOWN)
    .addItem("+", "+", false)
    .addItem("-", "-", true)
    .addItem("x", "x", false)
    .addItem("/", "/", false);

  const sections = CardService.newCardSection()
    .setHeader("Action_sample: Calculate")
    .setId("section_1")
    .addWidget(firstInput)
    .addWidget(selectionInput)
    .addWidget(secondInput)

  var card = CardService.newCardBuilder()
    .addSection(sections)
    .build();

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

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

  return outputVariables(variableDataMap);
}

測試步數

如要測試步驟，請為外掛程式設定測試部署作業，將步驟新增至代理程式，然後執行代理程式。

1. 為外掛程式設定測試部署作業：

   1. 在 Apps Script 編輯器中開啟指令碼專案。
   2. 依序點選「部署」>「測試部署作業」。
   3. 按一下 [安裝]。
   4. 按一下底部的「完成」。

   您可以與其他使用者的帳戶共用 Apps Script 專案 (必須具備編輯權限)，讓他們測試外掛程式。然後提示使用者按照先前的步驟操作。

   安裝完畢後，外掛程式會立即顯示在 Agents 中。你可能需要重新整理 Agents，外掛程式才會顯示。您也必須先授權外掛程式，才能使用。

   如要進一步瞭解測試部署作業，請參閱「安裝未發布的增益集」。

2. 開啟代理程式。

3. 建立包含步驟的代理程式：

   1. 按一下「新增代理程式」。
   2. 選取代理程式的啟動方式。測試步驟時，建議選擇可自行觸發的啟動器，例如傳送電子郵件給自己。如果步驟需要輸入變數，請將輸入變數設定為啟動器的輸出內容。
   3. 按一下「新增步驟」，選取您建立或更新的步驟，稱為「Calculate」。
   4. 設定步驟。在計算步驟中，選擇兩個值和數學運算。系統會自動儲存步驟。
   5. 如要測試步驟的輸出內容，請新增另一個步驟。舉例來說，如要在電子郵件中新增輸出內容，可以新增 Gmail 的「傳送郵件」步驟。在「訊息」中，按一下「變數」，然後選取步驟的輸出內容。在計算步驟中，依序選取「變數」 >「步驟 2：計算結果」 >「計算結果」。變數會以方塊形式顯示在「訊息」欄位中。
   6. 按一下「開啟」。代理程式已可執行。

4. 啟動代理程式的啟動器，即可執行代理程式。舉例來說，如果代理程式會在收到電子郵件時啟動，請傳送電子郵件給自己。

5. 確認代理程式是否正常運作。前往代理程式建構工具的「活動」分頁，即可查看記錄。如要瞭解如何在「活動」分頁中建立自訂記錄，請參閱活動記錄。

相關主題

• 輸入變數
• 驗證輸入變數
• 輸出變數
• 定義自訂資源
• 動態變數
• 記錄活動和錯誤
• Workspace Studio 事件物件