In dieser Anleitung wird erklärt, wie Sie eine Eingabevariable erstellen.
Für die Ausführung von Schritten sind bestimmte Informationen erforderlich. Für das Senden einer E-Mail ist beispielsweise eine E-Mail-Adresse erforderlich. Um diese erforderlichen Informationen für Schritte bereitzustellen, definieren Sie Eingabevariablen. Nach der Definition 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 Array inputs[] hat die folgenden Eigenschaften:
id: Eindeutige ID für eine Eingabevariable. Damit der Flow ein Eingabeelement der Konfigurationskarte dieser Eingabevariable zuordnen kann, muss mit dem Namen des entsprechenden Kartenelements übereinstimmen.description: Eine Beschreibung der Eingabevariable, die Endnutzern angezeigt wird.cardinality: Anzahl der zulässigen Werte. Mögliche Werte sind:SINGLE: Nur ein Wert ist zulässig.
dataType: Der Typ der akzeptierten Werte.dataTypehat die EigenschaftbasicType, die den Datentyp definiert. Gültige Werte sind:STRING: Ein alphanumerischer String.INTEGER: Eine Zahl.TIMESTAMP: Ein Zeitstempel im Format „Millisekunden seit der Unix-Epoche“. Beispiel: Der 27. November 2025, 16:49:02 Uhr UTC wird als1764262142988dargestellt.BOOLEAN: Entweder „true“ oder „false“.EMAIL_ADDRESS: Eine E-Mail-Adresse im Formatdana@example.com.
Im folgenden Beispiel werden drei Eingabevariablen für einen Schritt mit einem Taschenrechner 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": "calculatorDemo",
"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 Array inputs[] der Manifestdatei definiert ist.
Die in der Konfigurationskarte definierten Eingabe-Widgets müssen die folgenden Anforderungen erfüllen:
- Der
namejedes Eingabe-Widgets muss mit deridder entsprechenden Eingabevariable in der Manifestdatei übereinstimmen. - Die Kardinalität des Eingabe-Widgets muss mit der
cardinalityder Eingabevariable in der Manifestdatei übereinstimmen. - Der Datentyp des Eingabe-Widgets muss mit dem
dataTypeder Eingabevariable in der Manifestdatei übereinstimmen. Wenn die Eingabevariable dendataType„integer“ hat, kann sie keinen String enthalten.
Hilfe beim Erstellen von Kartenschnittstellen finden Sie in einer der folgenden Optionen:
- Card Builder: Ein interaktives Tool , mit dem Sie Karten erstellen und definieren können.
- Karte: in der Referenzdokumentation zur Google Workspace-Add-on API
- Card Service: Ein Apps Script-Dienst, mit dem Skripts Karten konfigurieren und erstellen können.
- Übersicht über kartenbasierte Schnittstellen: in der Entwicklerdokumentation für Google Workspace-Add-ons.
Im folgenden Beispiel wird für jedes Eingabe-Widget, das unter 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 input fields are configured to let the user select outputs from previous
* workflow steps as input values using the `hostAppDataSource` property.
*/
function onConfigCalculate() {
const firstInput = CardService.newTextInput()
.setFieldName("value1") // "FieldName" must match an "id" in the manifest file's inputs[] array.
.setTitle("First Value")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
);
const secondInput = CardService.newTextInput()
.setFieldName("value2") // "FieldName" must match an "id" in the manifest file's inputs[] array.
.setTitle("Second Value")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
);
const selectionInput = CardService.newSelectionInput()
.setTitle("operation")
.setFieldName("operation") // "FieldName" must match an "id" in the manifest file's inputs[] array.
.setType(CardService.SelectionInputType.DROPDOWN)
.addItem("+", "+", false)
.addItem("-", "-", true)
.addItem("x", "x", false)
.addItem("/", "/", false);
const sections = CardService.newCardSection()
.setHeader("Action_sample: Calculate")
.setId("section_1")
.addWidget(firstInput)
.addWidget(selectionInput)
.addWidget(secondInput)
let card = CardService.newCardBuilder()
.addSection(sections)
.build();
return card;
}
Ausgabevariablen aus vorherigen Schritten verwenden
Sie können Eingabevariablen so konfigurieren, dass sie Ausgabevariablen aus vorherigen Schritten im Workflow akzeptieren.
Variablenauswahl aktivieren
Wenn Nutzer Variablen aus vorherigen Schritten auswählen sollen, verwenden Sie die Eigenschaft includeVariables in den Widgets TextInput und SelectionInput.
Die Widgets TextInput und SelectionInput haben die folgenden Workspace Studio-spezifischen Funktionen:
includeVariables: Eine boolesche Eigenschaft, mit der Nutzer Variablen aus vorherigen Schritten auswählen können. Damit die Variablenauswahl in späteren Schritten angezeigt wird, müssen sowohl das Startereignis als auch mindestens eine entsprechende Ausgabevariable der Variablen zugeordnet sein.type: Ein aufgezählter Wert, der Vorschläge automatisch vervollständigt. Unterstützte Werte sind:USER: Bietet Vorschläge zur automatischen Vervollständigung für Personen in den Kontakten des Nutzers.SPACE: Bietet Vorschläge zur automatischen Vervollständigung für Google Chat-Gruppenbereiche, in denen der Nutzer Mitglied ist.
Wenn sowohl includeVariables als auch type festgelegt sind, kombiniert das Eingabefeld die beiden Funktionen. Nutzer können eine Variable des entsprechenden type aus einem Drop-down-Menü auswählen und Vorschläge zur automatischen Vervollständigung dafür sehen.
-
Abbildung 4: Ein Nutzer sieht Vorschläge zur automatischen Vervollständigung, wenn er einen Gruppenbereich auswählt. -
Abbildung 5: Ein Nutzer wählt die Ausgabevariable eines vorherigen Schritts aus dem Drop-down-Menü ➕ Variablen aus.
Nur eine Ausgabevariable mit einem Dreipunkt-Menü auswählen
Sie können ein SelectionInput
Widget so konfigurieren, dass Nutzer über ein Dreipunkt-Menü eine einzelne Ausgabevariable
aus einem vorherigen Schritt auswählen können.
Wenn Sie SelectionInputType auf OVERFLOW_MENU setzen, dient das Widget als spezielle Variablenauswahl. Im Gegensatz zur Verwendung von includeVariables mit TextInput, bei der Variablenwerte in Strings konvertiert werden, behält OVERFLOW_MENU den ursprünglichen Datentyp der ausgewählten Variablen bei.
Apps Script
const selectionInput = CardService.newSelectionInput()
.setFieldName("variable_picker_1")
.setTitle("Variable Picker")
.setType(
CardService.SelectionInputType.OVERFLOW_MENU
);
Nutzern erlauben, Text und Ausgabevariablen zu kombinieren
Sie können TextInput
Widgets so konfigurieren, dass Sie steuern, wie Nutzer mit Text und
Ausgabevariablen mit
setInputMode() interagieren.
RICH_TEXT: Ermöglicht Nutzern, Text und Ausgabevariablen zu kombinieren. Das Ergebnis ist ein einzelner verketteter String.PLAIN_TEXT: Beschränkt die Eingabe. Nutzer können entweder Text eingeben oder eine einzelne Ausgabevariable auswählen. Wenn Sie eine Variable auswählen, wird vorhandener Text ersetzt. Verwenden Sie diesen Modus, um bestimmte Datentypen zu erzwingen, die im Manifest definiert sind.
Die folgende Abbildung zeigt zwei TextInput-Widgets. Das erste ist als RICH_TEXT konfiguriert und enthält Text und eine Ausgabevariable. Das zweite ist als PLAIN_TEXT konfiguriert und lässt nur eine Ausgabevariable zu.
-
Abbildung 3: Als RICH_TEXTundPLAIN_TEXTkonfigurierte Text-Widgets.
Wir empfehlen, den Eingabemodus für alle TextInput-Widgets explizit festzulegen.
Hier ist die Manifestdatei zum Konfigurieren von TextInput-Widgets mit verschiedenen Eingabemodi:
JSON
{
"timeZone": "America/Toronto",
"dependencies": {},
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"addOns": {
"common": {
"name": "Text and output variable demo",
"logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "richTextDemo",
"state": "ACTIVE",
"name": "Rich Text Demo",
"description": "Show the difference between rich text and plain text TextInput widgets",
"workflowAction": {
"inputs": [
{
"id": "value1",
"description": "First user input",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
},
{
"id": "value2",
"description": "Second user input",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
}
],
"onConfigFunction": "onConfiguration",
"onExecuteFunction": "onExecution"
}
}
]
}
}
}
Hier ist der Code zum Konfigurieren von TextInput-Widgets mit verschiedenen Eingabemodi:
Apps Script
function onConfiguration() {
const input1 = CardService.newTextInput()
.setFieldName("value1")
.setId("value1")
.setTitle("Rich Text")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
)
// Set input mode to RICH_TEXT to allow mixed text and variables.
.setInputMode(CardService.TextInputMode.RICH_TEXT);
const input2 = CardService.newTextInput()
.setFieldName("value2")
.setId("value2")
.setTitle("Plain text")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
)
// Set input mode to PLAIN_TEXT to enforce single variable selection.
.setInputMode(CardService.TextInputMode.PLAIN_TEXT);
const section = CardService.newCardSection()
.addWidget(input1)
.addWidget(input2);
const card = CardService.newCardBuilder()
.addSection(section)
.build();
return card;
}
function onExecution(e) {
}
Buttons für die Variablenauswahl anpassen
Sie können den Button für die Variablenauswahl anpassen, indem Sie die Schaltflächengröße und die Beschriftung festlegen.
Schaltflächengröße
Verwenden Sie setVariableButtonSize() mit einem der folgenden VariableButtonSize-Enums, um die Schaltflächengröße festzulegen:
UNSPECIFIED: Die Standardeinstellung. Die Schaltfläche ist im Seitenbereich kompakt und in anderen Kontexten in voller Größe.COMPACT: Auf der Schaltfläche wird nur ein Pluszeichen (+) angezeigt.FULL_SIZE: Auf der Schaltfläche wird die vollständige Textbeschriftung angezeigt.
Beschriftung des Buttons
Verwenden Sie setVariableButtonLabel(), um den Schaltflächentext festzulegen.
Beispiel: Anpassung der Variablenauswahl
Im folgenden Beispiel wird gezeigt, wie Sie TextInput-Widgets mit verschiedenen Schaltflächengrößen für die Variablenauswahl und einer benutzerdefinierten Beschriftung konfigurieren.
-
Abbildung 1: Anpassung des Buttons für die Variablenauswahl im Web. -
Abbildung 2: Anpassung des Buttons für die Variablenauswahl im Seitenbereich eines Add-ons.
Hier ist die Manifestdatei zum Anpassen von Buttons für die Variablenauswahl:
JSON
{
"timeZone": "America/Los_Angeles",
"dependencies": {},
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"oauthScopes": [
"https://www.googleapis.com/auth/script.locale"
],
"addOns": {
"common": {
"name": "Variable button customization",
"logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "variable_picker_customization",
"state": "ACTIVE",
"name": "Variable Picker demo",
"description": "List all possible variable picker customization options",
"workflowAction": {
"onConfigFunction": "onUpdateCardConfigFunction",
"onExecuteFunction": "onUpdateCardExecuteFunction"
}
}
]
}
}
}
Hier ist der Code zum Anpassen von Buttons für die Variablenauswahl:
Apps Script
function onUpdateCardConfigFunction(event) {
const textInput1 = CardService.newTextInput()
.setFieldName("value1")
.setTitle("Regular variable picker button")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.UNSPECIFIED)
)
);
const textInput2 = CardService.newTextInput()
.setFieldName("value2")
.setTitle("Size: Unspecified")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.UNSPECIFIED)
)
);
const textInput3 = CardService.newTextInput()
.setFieldName("value3")
.setTitle("Size: Full size")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.FULL_SIZE)
)
);
const textInput4 = CardService.newTextInput()
.setFieldName("value4")
.setTitle("Size: Compact")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.COMPACT)
)
);
const textInput5 = CardService.newTextInput()
.setFieldName("value5")
.setTitle("Custom button label")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonLabel("New button label!")
)
);
var cardSection = CardService.newCardSection()
.addWidget(textInput1)
.addWidget(textInput2)
.addWidget(textInput3)
.addWidget(textInput4)
.addWidget(textInput5)
.setId("section_1");
var card = CardService.newCardBuilder().addSection(cardSection).build();
return card;
}
function onUpdateCardExecuteFunction(event) {
}
Automatische Vervollständigung von Google Workspace-Daten konfigurieren
Sie können auch Vorschläge zur automatischen Vervollständigung aus Daten in der Google Workspace-Umgebung des Nutzers generieren:
- Google Workspace-Nutzer:Nutzer in derselben Google Workspace-Organisation.
- Google Chat-Gruppenbereiche:Google Chat-Gruppenbereiche, in denen der Nutzer Mitglied ist.
Setzen Sie dazu
PlatformDataSource
im Widget
SelectionInput
und geben Sie
WorkflowDataSourceType
als USER oder SPACE an.
Apps Script
// User Autocomplete
var multiSelect2 =
CardService.newSelectionInput()
.setFieldName("value2")
.setTitle("User Autocomplete")
.setType(CardService.SelectionInputType.MULTI_SELECT)
.setMultiSelectMaxSelectedItems(3)
.setPlatformDataSource(
CardService.newPlatformDataSource()
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setType(CardService.WorkflowDataSourceType.USER)
))
);
// Chat Space Autocomplete
var multiSelect3 =
CardService.newSelectionInput()
.setFieldName("value3")
.setTitle("Chat Space Autocomplete")
.setType(CardService.SelectionInputType.MULTI_SELECT)
.setMultiSelectMaxSelectedItems(3)
.setPlatformDataSource(
CardService.newPlatformDataSource()
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setType(CardService.WorkflowDataSourceType.SPACE)
))
);
Beispiel: Kombinieren von Typen für die automatische Vervollständigung
Im folgenden Beispiel wird eine onConfig Funktion gezeigt, die eine Karte mit
drei SelectionInput
Widgets erstellt, die die automatische Vervollständigung auf Serverseite, für Nutzer und für Gruppenbereiche demonstrieren:
JSON
{
"timeZone": "America/Los_Angeles",
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"addOns": {
"common": {
"name": "Autocomplete Demo",
"logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "autocomplete_demo",
"state": "ACTIVE",
"name": "Autocomplete Demo",
"description": "Provide autocompletion in input fields",
"workflowAction": {
"inputs": [
{
"id": "value1",
"description": "A multi-select field with autocompletion",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
}
],
"onConfigFunction": "onConfigAutocomplete",
"onExecuteFunction": "onExecuteAutocomplete"
}
}
]
}
}
}
Apps Script
function onConfigAutocompleteTest(event) {
// Handle autocomplete request
if (event.workflow && event.workflow.elementUiAutocomplete) {
return handleAutocompleteRequest(event);
}
// Server-side autocomplete widget
var multiSelect1 =
CardService.newSelectionInput()
.setFieldName("value1")
.setTitle("Server Autocomplete")
.setType(CardService.SelectionInputType.MULTI_SELECT)
.setMultiSelectMaxSelectedItems(3)
.addDataSourceConfig(
CardService.newDataSourceConfig()
.setRemoteDataSource(
CardService.newAction().setFunctionName('getAutocompleteResults')
)
)
.addDataSourceConfig(
CardService.newDataSourceConfig()
.setPlatformDataSource(
CardService.newPlatformDataSource()
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
))
)
);
// User autocomplete widget
var multiSelect2 =
CardService.newSelectionInput()
.setFieldName("value2")
.setTitle("User Autocomplete")
.setType(CardService.SelectionInputType.MULTI_SELECT)
.setMultiSelectMaxSelectedItems(3)
.setPlatformDataSource(
CardService.newPlatformDataSource()
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setType(CardService.WorkflowDataSourceType.USER)
))
);
// Space autocomplete widget
var multiSelect3 =
CardService.newSelectionInput()
.setFieldName("value3")
.setTitle("Chat Space Autocomplete")
.setType(CardService.SelectionInputType.MULTI_SELECT)
.setMultiSelectMaxSelectedItems(3)
.setPlatformDataSource(
CardService.newPlatformDataSource()
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setType(CardService.WorkflowDataSourceType.SPACE)
))
);
var sectionBuilder =
CardService.newCardSection()
.addWidget(multiSelect1)
.addWidget(multiSelect2)
.addWidget(multiSelect3);
var card =
CardService.newCardBuilder()
.addSection(sectionBuilder)
.build();
return card;
}
function handleAutocompleteRequest(event) {
var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
var query = event.workflow.elementUiAutocomplete.query;
if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
return {};
}
// Query your data source to get results
let autocompleteResponse = AddOnsResponseService.newUpdateWidget()
.addSuggestion(
query + " option 1",
query + "_option1",
false,
"https://developers.google.com/workspace/add-ons/images/person-icon.png",
"option 1 bottom text"
)
.addSuggestion(
query + " option 2",
query + "_option2",
false,
"https://developers.google.com/workspace/add-ons/images/person-icon.png",
"option 2 bottom text"
).addSuggestion(
query + " option 3",
query + "_option3",
false,
"https://developers.google.com/workspace/add-ons/images/person-icon.png",
"option 3 bottom text"
);
const modifyAction = AddOnsResponseService.newAction()
.addModifyCard(
AddOnsResponseService.newModifyCard()
.setUpdateWidget(autocompleteResponse)
);
return AddOnsResponseService.newRenderActionBuilder()
.setAction(modifyAction)
.build();
}
Eingabevariable validieren
Als Best Practice sollten Sie prüfen, ob der Nutzer einen geeigneten Wert eingibt. Weitere Informationen finden Sie unter Eingabevariable validieren.
Weitere Informationen
- Eingabevariable validieren
- Ausgabevariablen
- Dynamische Variablen
- Aktivitäten und Fehler protokollieren
- Workspace Studio-Ereignisobjekte