构建步骤

本指南介绍了如何创建用户可以添加到 Google Workspace Flows 中的流程的步骤。

步骤是指流程的任务序列中的单个步骤。步骤无法启动流程。

例如,假设有一个执行算术运算的步骤。它会要求用户提供两个值和一个数学运算。然后对这些值执行数学运算并输出结果。

用户将计算器步骤配置为流程的一部分。

图 1:用户将计算器步骤配置为流程的一部分。

如需构建步骤,请在插件的清单文件中对其进行配置,在 Google Workspace 插件的代码中编写应用逻辑,然后部署并测试该步骤。在 Alpha 阶段,请勿发布扩展 Flows 的插件。

定义步骤

如需配置某个步,请在清单文件中定义该步,并在代码中编写其应用逻辑。

在清单文件中定义相应步骤

在清单文件 appsscript.json 中:

  1. onConfigFunctiononExecuteFunction 设置为插件代码中相应函数的名称。在此示例中,函数分别称为 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 定义了一个配置卡片。

    卡片是插件中界面的构建块。卡片支持已定义的布局、按钮等互动式界面元素以及图片等富媒体。卡片用于从用户那里获取步骤运行所需的数据,例如用于发送电子邮件的电子邮件地址。

    OnConfigFunction 会返回一个包含卡片的 RenderActions 对象。此卡片定义了用户设置步数数据的界面。在此示例中,onConfigFunction 构建了一个卡片,要求用户提供两个值和一个数学运算。

  2. 在此示例中,写入名为 onExecuteCalculate()onExecuteFunction。 当您的步骤在 flow 中运行时,系统会运行 OnExecuteFunction。用户在配置期间设置的任何输入值(如 onConfigurationFunction 中所定义)都会传递给 OnExecuteFunction

    编写 OnExecuteFunction(),使其使用提供的输入同步执行任务。请注意,OnExecuteFunction() 必须返回流程清单中定义的所有输出,否则会发生错误。

此代码示例包含一个支持函数 outputVariables(),该函数会构建提供的变量并将其作为输出从该步骤发送。

您的步数数据已准备就绪,可以进行测试了。

以下是“计算器”步骤的代码:

Apps 脚本

/**
 * 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
        ]
      },
  }]);
}

测试步数

如需测试该步骤,请为插件设置测试部署,将该步骤添加到流程中,然后运行该流程。

  1. 为插件设置测试部署:

    1. 在 Apps 脚本编辑器中打开脚本项目。
    2. 依次点击部署 > 测试部署
    3. 点击安装
    4. 点击底部的完成

    您可以与其他用户共享 Apps 脚本项目(需要具有修改权限),以便他们测试该插件。然后提示用户按照之前的步骤操作。

    安装完毕后,该插件会立即在 Flows 中提供。您可能需要刷新 Flows,然后该插件才会显示。您还必须先授权该插件,然后才能使用它。

    如需详细了解测试部署,请参阅安装未发布的插件

  2. 打开“流程”。

  3. 创建包含您的步骤的流:

    1. 点击新建流程
    2. 选择流程的启动方式。在测试某个步骤时,最好选择可以自行触发的启动器,例如给自己发送电子邮件。如果您的步骤需要输入变量,请将输入变量配置为启动器的输出的一部分。
    3. 点击 添加步骤。选择您构建或更新的步骤,即“计算”步骤。
    4. 配置相应步骤。在计算步骤中,选择两个值和一个数学运算。系统会自动保存相应步骤。
    5. 如需测试步骤的输出,请添加另一个步骤。例如,如需向电子邮件添加输出,您可以添加 Gmail 的发送邮件步骤。在消息中,依次点击 变量,然后选择相应步骤的输出。对于计算步骤,请依次选择变量 > 第 2 步:计算结果 > 计算结果。该变量会以条状标签的形式显示在消息字段中。
    6. 点击开启。 您的流可以运行了。
  4. 通过触发流程的启动器来运行流程。例如,如果您的流在收到电子邮件时开始,请给自己发送一封电子邮件。

  5. 验证流程是否按预期运行。如需查看日志,请访问流程构建器的活动标签页。 如需了解如何在“活动”标签页中创建自定义日志,请参阅活动日志