本指南介绍了如何创建用户可以添加到 Google Workspace Flows 中的流程的步骤。
步骤是指流程的任务序列中的单个步骤。步骤无法启动流程。
例如,假设有一个执行算术运算的步骤。它会要求用户提供两个值和一个数学运算。然后对这些值执行数学运算并输出结果。
如需构建步骤,请在插件的清单文件中对其进行配置,在 Google Workspace 插件的代码中编写应用逻辑,然后部署并测试该步骤。在 Alpha 阶段,请勿发布扩展 Flows 的插件。
定义步骤
如需配置某个步,请在清单文件中定义该步,并在代码中编写其应用逻辑。
在清单文件中定义相应步骤
在清单文件 appsscript.json 中:
- 将
onConfigFunction和onExecuteFunction设置为插件代码中相应函数的名称。在此示例中,函数分别称为onConfigCalculate()和onExecuteCalculate()。onConfigFunction设置并配置相应步骤。如有必要,收集用户执行相应步骤所需的数据,例如要发送电子邮件的地址。在本指南的示例中,我们要求提供两个值和一个数学运算。onExecuteFunction执行相应步骤。如果从用户处收集了数据,则该数据会传递给此函数。如果适用,则返回输出。在本指南的示例中,输出数学计算的结果。
设置所需的输入和输出,以便该步骤收集数据并将其发送到后续步骤。在此示例中,要求用户提供两个值以及在
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"
}
}
]
}
}
}
接下来,通过在代码中定义步骤来编写支持代码。
在代码中定义相应步骤
在应用代码中,执行以下操作:
编写
onConfigFunction,在本示例中称为onConfigCalculate()。 用户将此步骤添加到流程后,可以在流程构建器中配置该步骤的各个方面。 为了从用户那里收集所需信息,onConfigFunction定义了一个配置卡片。卡片是插件中界面的构建块。卡片支持已定义的布局、按钮等互动式界面元素以及图片等富媒体。卡片用于从用户那里获取步骤运行所需的数据,例如用于发送电子邮件的电子邮件地址。
OnConfigFunction会返回一个包含卡片的RenderActions对象。此卡片定义了用户设置步数数据的界面。在此示例中,onConfigFunction构建了一个卡片,要求用户提供两个值和一个数学运算。在此示例中,写入名为
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
]
},
}]);
}
测试步数
如需测试该步骤,请为插件设置测试部署,将该步骤添加到流程中,然后运行该流程。
为插件设置测试部署:
- 在 Apps 脚本编辑器中打开脚本项目。
- 依次点击部署 > 测试部署。
- 点击安装。
- 点击底部的完成。
您可以与其他用户共享 Apps 脚本项目(需要具有修改权限),以便他们测试该插件。然后提示用户按照之前的步骤操作。
安装完毕后,该插件会立即在 Flows 中提供。您可能需要刷新 Flows,然后该插件才会显示。您还必须先授权该插件,然后才能使用它。
如需详细了解测试部署,请参阅安装未发布的插件。
打开“流程”。
创建包含您的步骤的流:
- 点击新建流程。
- 选择流程的启动方式。在测试某个步骤时,最好选择可以自行触发的启动器,例如给自己发送电子邮件。如果您的步骤需要输入变量,请将输入变量配置为启动器的输出的一部分。
- 点击 添加步骤。选择您构建或更新的步骤,即“计算”步骤。
- 配置相应步骤。在计算步骤中,选择两个值和一个数学运算。系统会自动保存相应步骤。
- 如需测试步骤的输出,请添加另一个步骤。例如,如需向电子邮件添加输出,您可以添加 Gmail 的发送邮件步骤。在消息中,依次点击 变量,然后选择相应步骤的输出。对于计算步骤,请依次选择变量 > 第 2 步:计算结果 > 计算结果。该变量会以条状标签的形式显示在消息字段中。
- 点击开启。 您的流可以运行了。
通过触发流程的启动器来运行流程。例如,如果您的流在收到电子邮件时开始,请给自己发送一封电子邮件。
验证流程是否按预期运行。如需查看日志,请访问流程构建器的活动标签页。 如需了解如何在“活动”标签页中创建自定义日志,请参阅活动日志。