Diese Seite wurde von der Cloud Translation API übersetzt.

Eingabevariable validieren

In diesem Leitfaden wird beschrieben, wie Sie eine Eingabevariable validieren.

Beim Definieren einer Eingabevariablen sollten Sie als Best Practice prüfen, ob der Nutzer einen geeigneten Wert eingibt. Wenn Sie den Nutzer beispielsweise auffordern, eine Ziffer einzugeben, und prüfen, ob er 1 anstelle von a eingibt, wird bestätigt, dass Ihr Schritt fehlerfrei ausgeführt wird.

Es gibt zwei Möglichkeiten, eine Eingabevariable zu validieren:

Clientseitige Validierung: Bei der clientseitigen Validierung wird die Eingabe des Nutzers direkt auf seinem Gerät überprüft. Der Nutzer erhält sofortiges Feedback und kann Fehler in seiner Eingabe korrigieren, während er den Schritt konfiguriert.
Serverseitige Validierung: Bei der serverseitigen Validierung können Sie während der Validierung Logik auf dem Server ausführen. Das ist nützlich, wenn Sie Informationen abrufen müssen, die der Client nicht hat, z. B. Daten in anderen Systemen oder Datenbanken.

Clientseitige Validierung

Es gibt zwei Möglichkeiten, die clientseitige Validierung zu implementieren:

Für die grundlegende Validierung, z. B. um zu prüfen, ob ein Widget weniger als eine bestimmte Anzahl von Zeichen oder das Symbol @ enthält, rufen Sie die Klasse Validation des Card-Dienstes des Google Workspace-Add-ons auf.
Für eine robuste Validierung, z. B. den Vergleich von Widget-Werten mit anderen Widget-Werten, können Sie den folgenden unterstützten Karten-Widgets mit CardService eine CEL-Validierung (Common Expression Language) hinzufügen.

`Validation`-Klasse aufrufen

Im folgenden Beispiel wird geprüft, ob ein TextInput-Widget maximal 10 Zeichen enthält:

Apps Script

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

Für zusätzliche Validierungsoptionen verwenden Sie die CEL-Validierung.

CEL-Validierung

Die Common Expression Language (CEL)-Validierung bietet sofortige Eingabeüberprüfungen ohne die Latenz der serverseitigen Validierung. Dazu werden Eingabewertprüfungen, die nicht vom Abrufen von Daten aus anderen Diensten abhängen, auf die Clientseite ausgelagert.

Sie können CEL auch verwenden, um Kartenverhalten zu erstellen, z. B. das Ein- oder Ausblenden eines Widgets in Abhängigkeit vom Ergebnis der Validierung. Dieses Verhalten ist nützlich, um eine Fehlermeldung ein- oder auszublenden, die Nutzern hilft, ihre Eingaben zu korrigieren.

Für eine vollständige CEL-Validierung sind die folgenden Komponenten erforderlich:

ExpressionData in der Karte: Enthält die angegebene Validierungslogik und die Logik zum Auslösen von Widgets, wenn eine der definierten Bedingungen erfüllt ist.
- Id: Eine eindeutige Kennung für die ExpressionData in der aktuellen Karte.
- Expression: Der CEL-String, der die Validierungslogik definiert (z.B. "value1 == value2").
- Conditions: Eine Liste von Bedingungen, die eine Auswahl vordefinierter Validierungsergebnisse (SUCCESS oder FAILURE) enthält. Bedingungen sind über Triggers mit einem gemeinsamen actionRuleId an die Widget-Seite EventAction gebunden.
- Kartenbezogen EventAction: Aktiviert CEL-Validierungen auf der Karte und verknüpft das Feld ExpressionData über Post-Event-Trigger mit Ergebnis-Widgets.
  - actionRuleId: Eindeutige ID für diese EventAction.
  - ExpressionDataAction: Auf START_EXPRESSION_EVALUATION setzen, um anzugeben, dass mit dieser Aktion die CEL-Auswertung beginnt.
  - Trigger: Verbindet die Conditions mit der Widget-seitigen EventActions basierend auf der actionRuleId.
EventAction auf Widget-Ebene: Steuert das Verhalten des Ergebnis-Widgets, wenn die Bedingung für Erfolg oder Fehler erfüllt ist. Ein Ergebnis-Widget kann beispielsweise ein TextParagraph sein, das eine Fehlermeldung enthält, die erst sichtbar wird, wenn die Validierung fehlschlägt.
- actionRuleId: Stimmt mit dem actionRuleId auf der Kartenseite Trigger überein.
- CommonWidgetAction: Definiert Aktionen, die keine Auswertungen umfassen, z. B. das Aktualisieren der Widget-Sichtbarkeit.
  - UpdateVisibilityAction: Eine Aktion, mit der der Sichtbarkeitsstatus eines Widgets (VISIBLE oder HIDDEN) aktualisiert wird.

Im folgenden Beispiel wird gezeigt, wie die CEL-Validierung implementiert wird, um zu prüfen, ob zwei Texteingaben gleich sind. Wenn sie nicht übereinstimmen, wird eine Fehlermeldung angezeigt.

Abbildung 1:Wenn die failCondition erfüllt ist (Eingaben sind nicht gleich), wird das Fehlermeldungs-Widget auf VISIBLE gesetzt und angezeigt.
Abbildung 2:Wenn die successCondition erfüllt ist (Eingaben sind gleich), wird das Fehlermeldungs-Widget auf HIDDEN gesetzt und nicht angezeigt.

Hier sind der Beispielanwendungscode und die JSON-Manifestdatei:

Apps Script

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-Manifestdatei

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

Unterstützte CEL-Validierungs-Widgets und ‑Vorgänge

Karten-Widgets, die die CEL-Validierung unterstützen

Die folgenden Widgets unterstützen die CEL-Validierung:

TextInput
SelectionInput
DateTimePicker

Unterstützte CEL-Validierungsvorgänge

Arithmetische Operationen
- +: Addiert zwei int64-, uint64- oder double-Zahlen.
- -: Subtrahiert zwei int64-, uint64- oder double-Zahlen.
- *: Multipliziert zwei int64-, uint64- oder double-Zahlen.
- /: Dividiert zwei int64-, uint64- oder double-Zahlen (Ganzzahldivision).
- %: Berechnet den Modulo von zwei int64- oder uint64-Zahlen.
- -: Negiert eine int64- oder uint64-Zahl.
Logische Operationen:
- &&: Führt einen logischen AND-Vorgang für zwei boolesche Werte aus.
- ||: Führt einen logischen OR-Vorgang für zwei boolesche Werte aus.
- !: Führt einen logischen NOT-Vorgang für einen booleschen Wert aus.
Vergleichsvorgänge:
- ==: Prüft, ob zwei Werte gleich sind. Unterstützt Zahlen und Listen.
- !=: Prüft, ob zwei Werte ungleich sind. Unterstützt Zahlen und Listen.
- <: Prüft, ob die erste int64-, uint64- oder double-Zahl kleiner als die zweite ist.
- <=: Prüft, ob die erste int64-, uint64- oder double-Zahl kleiner als oder gleich der zweiten ist.
- >: Prüft, ob die erste int64-, uint64- oder double-Zahl größer als die zweite ist.
- >=: Prüft, ob die erste int64-, uint64- oder double-Zahl größer als oder gleich der zweiten ist.
Vorgänge auflisten:
- in: Prüft, ob ein Wert in einer Liste vorhanden ist. Unterstützt Zahlen, Strings und verschachtelte Listen.
- size: Gibt die Anzahl der Elemente in einer Liste zurück. Unterstützt Zahlen und verschachtelte Listen.

Nicht unterstützte CEL-Validierungsszenarien

Falsche Argumentgrößen für binäre Operationen: Für binäre Operationen (z. B. add_int64, „ist gleich“) sind genau zwei Argumente erforderlich. Wenn Sie eine andere Anzahl von Argumenten angeben, wird ein Fehler ausgegeben.
Falsche Argumentgrößen für unäre Operationen: Unäre Operationen (z. B. negate_int64) erfordern genau ein Argument. Wenn Sie eine andere Anzahl von Argumenten angeben, wird ein Fehler ausgegeben.
Nicht unterstützte Typen in numerischen Operationen: Numerische binäre und unäre Operationen akzeptieren nur Zahlenargumente. Wenn Sie andere Typen (z. B. boolesche Werte) angeben, wird ein Fehler ausgegeben.

Serverseitige Validierung

Bei der serverseitigen Validierung können Sie serverseitige Logik ausführen, indem Sie die onSaveFunction() im Code des Schritts angeben. Wenn der Nutzer die Konfigurationskarte des Schritts verlässt, wird onSaveFunction() ausgeführt und Sie können die Eingabe des Nutzers überprüfen.

Wenn die Eingabe des Nutzers gültig ist, gib saveWorkflowAction zurück.

Wenn die Eingabe des Nutzers ungültig ist, geben Sie eine Konfigurationskarte zurück, auf der dem Nutzer eine Fehlermeldung angezeigt wird, in der erklärt wird, wie der Fehler behoben werden kann.

Da die serverseitige Validierung asynchron erfolgt, erfährt der Nutzer möglicherweise erst beim Veröffentlichen des Ablaufs von dem Eingabefehler.

Die id jedes validierten Eingabefelds in der Manifestdatei muss mit der name eines Karten-Widgets im Code übereinstimmen.

Im folgenden Beispiel wird geprüft, ob die Texteingabe eines Nutzers das @-Zeichen enthält:

Manifestdatei

Der Manifestdateiausschnitt gibt einen onSaveFunction() mit dem Namen „onSave“ an:

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

Anwendungscode

Der Code des Schritts enthält eine Funktion namens onSave(). Es wird geprüft, ob ein vom Nutzer eingegebener String das Zeichen „@“ enthält. Wenn ja, wird der Flow-Schritt gespeichert. Andernfalls wird eine Konfigurationskarte mit einer Fehlermeldung zurückgegeben, in der erklärt wird, wie der Fehler behoben werden kann.

Apps Script

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

Eingabevariable validieren Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Clientseitige Validierung

Validation-Klasse aufrufen

Apps Script

CEL-Validierung

Apps Script

JSON-Manifestdatei

Unterstützte CEL-Validierungs-Widgets und ‑Vorgänge

Karten-Widgets, die die CEL-Validierung unterstützen

Unterstützte CEL-Validierungsvorgänge

Nicht unterstützte CEL-Validierungsszenarien

Serverseitige Validierung

Manifestdatei

JSON

Anwendungscode

Apps Script

Weitere Informationen

Eingabevariable validieren

`Validation`-Klasse aufrufen