此页面由 Cloud Translation API 翻译。

验证输入变量

本指南介绍了如何验证输入变量。

定义输入变量时，最佳实践是验证用户是否输入了适当的值。例如，如果您要求用户输入数字，那么验证用户输入的是 1 而不是 a，即可验证您的步骤是否正常运行。

您可以通过以下两种方式验证输入变量：

客户端验证：借助客户端验证，您可以直接在用户的设备上验证其输入内容。用户在配置步骤时会立即收到反馈，并可以更正输入中的任何错误。
服务器端验证：借助服务器端验证，您可以在验证期间在服务器上运行逻辑，这在您需要查找客户端没有的信息（例如其他系统或数据库中的数据）时非常有用。

客户端验证

您可以通过以下两种方式实现客户端验证：

对于基本验证（例如验证 widget 是否包含少于一定数量的字符或是否包含 @ 符号），请调用 Google Workspace 加载项的 Card 服务的 Validation 类。
如需进行稳健的验证（例如将 widget 值与其他 widget 值进行比较），您可以使用 CardService 向以下受支持的卡片 widget 添加通用表达式语言 (CEL) 验证。

调用 `Validation` 类

以下示例验证 TextInput widget 是否包含 10 个或更少的字符：

Apps 脚本

const validation = CardService.newValidation().setCharacterLimit('10').setInputType(
    CardService.InputType.TEXT);

如需了解其他验证选项，请使用 CEL 验证。

CEL 验证

通用表达式语言 (CEL) 验证可将不依赖于从其他服务查找数据的输入值检查分流到客户端，从而实现即时输入检查，而不会产生服务器端验证的延迟。

您还可以使用 CEL 创建卡片行为，例如根据验证结果显示或隐藏 widget。这种行为对于显示或隐藏有助于用户更正输入的错误消息非常有用。

构建完整的 CEL 验证涉及以下组件：

卡片中的 ExpressionData：包含指定的验证逻辑和 widget 触发逻辑（当满足定义的某个条件时）。
- Id：当前卡片中 ExpressionData 的唯一标识符。
- Expression：用于定义验证逻辑的 CEL 字符串（例如，"value1 == value2"）。
- Conditions：一个条件列表，其中包含一组预定义的验证结果（SUCCESS 或 FAILURE）。条件通过共享的 actionRuleId 与 widget 端 EventAction 的 Triggers 相关联。
- 卡级 EventAction：在卡中启用 CEL 验证，并通过后事件触发器将 ExpressionData 字段与结果 widget 相关联。
  - actionRuleId：相应 EventAction 的唯一 ID。
  - ExpressionDataAction：设置为 START_EXPRESSION_EVALUATION 以表明此操作会启动 CEL 评估。
  - Trigger：根据 actionRuleId 将 Conditions 连接到 widget 端 EventActions。
widget 级 EventAction：控制结果 widget 在满足成功或失败条件时的行为。例如，结果 widget 可以是包含错误消息的 TextParagraph，该消息仅在验证失败时显示。
- actionRuleId：与卡片端 Trigger 中的 actionRuleId 相匹配。
- CommonWidgetAction：定义不涉及评估的操作，例如更新 widget 可见性。
  - UpdateVisibilityAction：用于更新 widget 可见性状态（VISIBLE 或 HIDDEN）的操作。

以下示例演示了如何实现 CEL 验证来检查两个文本输入是否相等。如果不相等，系统会显示一条错误消息。

图 1：当满足 failCondition（输入不相等）时，错误消息 widget 会设置为 VISIBLE 并显示。
图 2：当满足 successCondition（输入相等）时，错误消息 widget 会设置为 HIDDEN，并且不会显示。

以下是示例应用代码和 JSON 清单文件：

Apps 脚本

function onConfig() {

  // Create a Card
  let card = CardService.newCardBuilder();

  const textInput_1 = CardService.newTextInput()
    .setTitle("Input number 1")
    .setFieldName("value1"); // FieldName's value must match a corresponding ID defined in the inputs[] array in the manifest file.
  const textInput_2 = CardService.newTextInput()
    .setTitle("Input number 2")
    .setFieldName("value2"); // FieldName's value must match a corresponding ID defined in the inputs[] array in the manifest file.
  let sections = CardService.newCardSection()
    .setHeader("Two number equals")
    .addWidget(textInput_1)
    .addWidget(textInput_2);

  // CEL Validation

  // Define Conditions
  const condition_success = CardService.newCondition()
    .setActionRuleId("CEL_TEXTINPUT_SUCCESS_RULE_ID")
    .setExpressionDataCondition(
      CardService.newExpressionDataCondition()
      .setConditionType(
        CardService.ExpressionDataConditionType.EXPRESSION_EVALUATION_SUCCESS));
  const condition_fail = CardService.newCondition()
    .setActionRuleId("CEL_TEXTINPUT_FAILURE_RULE_ID")
    .setExpressionDataCondition(
      CardService.newExpressionDataCondition()
      .setConditionType(
        CardService.ExpressionDataConditionType.EXPRESSION_EVALUATION_FAILURE));

  // Define Card-side EventAction
  const expressionDataAction = CardService.newExpressionDataAction()
    .setActionType(
      CardService.ExpressionDataActionType.START_EXPRESSION_EVALUATION);
  // Define Triggers for each Condition respectively
  const trigger_success = CardService.newTrigger()
    .setActionRuleId("CEL_TEXTINPUT_SUCCESS_RULE_ID");
  const trigger_failure = CardService.newTrigger()
    .setActionRuleId("CEL_TEXTINPUT_FAILURE_RULE_ID");

  const eventAction = CardService.newEventAction()
    .setActionRuleId("CEL_TEXTINPUT_EVALUATION_RULE_ID")
    .setExpressionDataAction(expressionDataAction)
    .addPostEventTrigger(trigger_success)
    .addPostEventTrigger(trigger_failure);

  // Define ExpressionData for the current Card
  const expressionData = CardService.newExpressionData()
    .setId("expData_id")
    .setExpression("value1 == value2") // CEL expression
    .addCondition(condition_success)
    .addCondition(condition_fail)
    .addEventAction(eventAction);
  card = card.addExpressionData(expressionData);

  // Create Widget-side EventActions and a widget to display error message
  const widgetEventActionFail = CardService.newEventAction()
    .setActionRuleId("CEL_TEXTINPUT_FAILURE_RULE_ID")
    .setCommonWidgetAction(
      CardService.newCommonWidgetAction()
      .setUpdateVisibilityAction(
        CardService.newUpdateVisibilityAction()
        .setVisibility(
          CardService.Visibility.VISIBLE)));
  const widgetEventActionSuccess = CardService.newEventAction()
    .setActionRuleId("CEL_TEXTINPUT_SUCCESS_RULE_ID")
    .setCommonWidgetAction(
      CardService.newCommonWidgetAction()
      .setUpdateVisibilityAction(
        CardService.newUpdateVisibilityAction()
        .setVisibility(
          CardService.Visibility.HIDDEN)));
  const errorWidget = CardService.newTextParagraph()
    .setText("The first and second value must match.")
    .setVisibility(CardService.Visibility.HIDDEN) // Initially hidden
    .addEventAction(widgetEventActionFail)
    .addEventAction(widgetEventActionSuccess);
  sections = sections.addWidget(errorWidget);

  card = card.addSection(sections);
  // Build and return the Card
  return card.build();
}

JSON 清单文件

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "CEL validation example",
      "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": "CEL Demo",
          "description": "Demonstrates CEL Validation",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "The first number",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "value2",
                "description": "The second number",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              }
            ],
            "onConfigFunction": "onConfig",
            "onExecuteFunction": "onExecute"
          }
        }
      ]
    }
  }
}

支持的 CEL 验证 widget 和操作

支持 CEL 验证的卡片 widget

以下 widget 支持 CEL 验证：

TextInput
SelectionInput
DateTimePicker

支持的 CEL 验证操作

算术运算
- +：添加两个 int64、uint64 或 double 数字。
- -：减去两个 int64、uint64 或 double 数。
- *：将两个 int64、uint64 或 double 数相乘。
- /：将两个 int64、uint64 或 double 数相除（整数除法）。
- %：计算两个 int64 或 uint64 数的模。
- -：对 int64 或 uint64 数值取反。
逻辑运算：
- &&：对两个布尔值执行逻辑 AND 运算。
- ||：对两个布尔值执行逻辑 OR 运算。
- !：对布尔值执行逻辑 NOT 运算。
比较操作：
- ==：检查两个值是否相等。支持数字和列表。
- !=：检查两个值是否不相等。支持数字和列表。
- <：检查第一个数字（int64、uint64 或 double）是否小于第二个数字。
- <=：检查第一个数（int64、uint64 或 double）是否小于或等于第二个数。
- >：检查第一个数字（int64、uint64 或 double）是否大于第二个数字。
- >=：检查第一个数字（int64、uint64 或 double）是否大于或等于第二个数字。
列出操作：
- in：检查某个值是否在列表中。支持数字、字符串和嵌套列表。
- size：返回列表中的项目数。支持数字和嵌套列表。

不受支持的 CEL 验证场景

二元运算的实参大小不正确：二元运算（例如 add_int64、等于）需要正好两个实参。如果提供的实参数量不同，系统会抛出错误。
一元运算的实参大小不正确：一元运算（例如 negate_int64）需要一个实参。如果提供的实参数量不同，系统会抛出错误。
数值运算中不支持的类型：数值二元运算和一元运算仅接受数值实参。提供其他类型（例如，布尔值）将抛出错误。

服务器端验证

借助服务器端验证，您可以在步骤的代码中指定 onSaveFunction()，以运行服务器端逻辑。当用户离开相应步骤的配置卡片时，onSaveFunction() 会运行，以便您验证用户的输入。

如果用户输入有效，则返回 saveWorkflowAction。

如果用户输入无效，则返回一个配置卡，其中向用户显示一条错误消息，说明如何解决该错误。

由于服务器端验证是异步的，因此用户可能直到发布流程后才知道输入错误。

清单文件中每个经过验证的输入的 id 都必须与代码中某个卡片 widget 的 name 相匹配。

以下示例验证用户文本输入是否包含“@”符号：

清单文件

清单文件摘录指定了一个名为“onSave”的 onSaveFunction()：

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Server-side validation example",
      "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 an email address",
          "workflowAction": {
            "inputs": [
              {
                "id": "email",
                "description": "email address",
                "cardinality": "SINGLE",
                "required": true,
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigCalculate",
            "onExecuteFunction": "onExecuteCalculate",
            "onSaveFunction": "onSave"
          }
        }
      ]
    }
  }
}

应用代码

相应步骤的代码包含一个名为 onSave() 的函数。它会验证用户输入的字符串是否包含 @。如果包含，则保存相应流程步骤。如果不是，则返回一个配置卡，其中包含一条错误消息，说明如何修正错误。

Apps 脚本

/**
 * Validates user input asynchronously when the user
 * navigates away from a step's configuration card.
*/
function onSave(event) {

  // "email" matches the input ID specified in the manifest file.
  var email = event.workflow.actionInvocation.inputs["email"];

  // Validate that the email address contains an "@" sign:
  if(email.includes("@")) {

  // If successfully validated, save and proceed.
    return {
      "hostAppAction" : {
        "workflowAction" : {
          "saveWorkflowAction" : {}
        }
      }
    };

  // If the input is invalid, return a card with an error message
  } else {

var card = {
    "sections": [
      {
        "header": "Collect Email",
        "widgets": [
          {
            "textInput": {
              "name": "email",
              "label": "email address",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          },
          {
            "textParagraph": {
              "text": "<b>Error:</b> Email addresses must include the '@' sign.",
              "maxLines": 1
            }
          }
        ]
      }
    ]
  };
  return pushCard(card);
  }
}

验证输入变量 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

客户端验证

调用 Validation 类

Apps 脚本

CEL 验证

Apps 脚本

JSON 清单文件

支持的 CEL 验证 widget 和操作

支持 CEL 验证的卡片 widget

支持的 CEL 验证操作

不受支持的 CEL 验证场景

服务器端验证

清单文件

JSON

应用代码

Apps 脚本

相关主题

验证输入变量

调用 `Validation` 类