Daten mit einer Eingabevariable erheben

In dieser Anleitung wird beschrieben, wie Sie eine Eingabevariable erstellen.

Für die Ausführung von Schritten sind bestimmte Informationen erforderlich. Zum Senden einer E‑Mail ist beispielsweise eine E‑Mail-Adresse erforderlich. Um diese Informationen bereitzustellen, müssen Sie Eingabevariablen definieren. Nachdem sie definiert wurden, werden Eingabevariablen in der Regel vom Nutzer auf der Konfigurationskarte eines Schritts festgelegt, während der Nutzer den Schritt einrichtet.

Definieren Sie die Eingabevariable an zwei Stellen: in der Manifestdatei des Add-ons und im Code mit einer Konfigurationskarte, auf der Nutzer Werte für Eingabevariablen eingeben können.

Eingabevariable in der Manifestdatei definieren

Geben Sie in der Manifestdatei Eingabevariablen mit dem Array inputs[] an. Jedes Element im inputs[]-Array hat die folgenden Attribute:

  • id: Eindeutige Kennung für eine Eingabevariable. Damit der Ablauf ein Eingabeelement der Konfigurationskarte dieser Eingabevariablen zuordnen kann, muss der Name mit dem Namen des entsprechenden Kartenelements übereinstimmen.
  • description: Eine Beschreibung der Eingabevariable, die Endnutzern angezeigt wird.
  • cardinality: Wie viele Werte zulässig sind. Mögliche Werte:
    • SINGLE: Es ist nur ein Wert zulässig.
  • dataType: Der Typ der akzeptierten Werte. dataType hat das Attribut basicType, das den Datentyp definiert. Gültige Werte sind:
    • STRING: Ein alphanumerischer String.
    • INTEGER: Eine Zahl.
    • TIMESTAMP: Ein Zeitstempel im ISO 8601-Format. In ISO 8601 wird der 15. März 2025 beispielsweise als 2025-03-15 dargestellt.
    • BOOLEAN: entweder „true“ oder „false“.
    • EMAIL_ADDRESS: Eine E-Mail-Adresse im Format dana@example.com.

Im folgenden Beispiel werden drei Eingabevariablen für einen Berechnungsschritt definiert. Die ersten beiden Eingabevariablen sind Ganzzahlen und die dritte ist eine arithmetische Operation.

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

Eingabevariable im Code definieren

Der Code des Schritts enthält eine Funktion namens onConfigFunction(), die eine Konfigurationskarte zurückgibt, die ein Eingabekarten-Widget für jede Eingabevariable definiert, die im inputs[]-Array der Manifestdatei definiert ist.

Für die in der Konfigurationskarte definierten Eingabe-Widgets gelten die folgenden Anforderungen:

  • Die name jedes Eingabe-Widgets muss mit der id der entsprechenden Eingabevariable in der Manifestdatei übereinstimmen.
  • Die Kardinalität des Eingabe-Widgets muss mit dem cardinality der Eingabevariable in der Manifestdatei übereinstimmen.
  • Der Datentyp des Eingabe-Widgets muss mit dem dataType der Eingabevariable in der Manifestdatei übereinstimmen. Wenn die Eingabevariable den Typ dataType (Ganzzahl) hat, kann sie keinen String enthalten.

Hilfe beim Erstellen von Kartenoberflächen finden Sie unter einer der folgenden Optionen:

Im folgenden Beispiel wird für jedes Eingabe-Widget, das in Eingabevariable in der Manifestdatei definieren definiert ist, eine Konfigurationskarte zurückgegeben.

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 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 onConfigFunction() {
  var card = {
    "sections": [
      {
        "header": "Step example: Calculate",
        "widgets": [
          {
            "textInput": {
              "name": "value1", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "First value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          },
          {
            "selectionInput": {
              "name": "operation", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "Operation",
              "type": "DROPDOWN",
              "items": [
                {
                  "text": "+",
                  "value": "+",
                },
                {
                  "text": "-",
                  "value": "-",
                },
                {
                  "text": "x",
                  "value": "x",
                },
                {
                  "text": "/",
                  "value": "/",
                }
              ]
            }
          },
          {
            "textInput": {
              "name": "value2", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "Second value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

Eingabevariable validieren

Als Best Practice sollten Sie prüfen, ob der Nutzer einen geeigneten Wert eingibt. Weitere Informationen finden Sie unter Eingabevariable validieren.