Raccogliere dati con una variabile di input

Anteprima limitata: L'estensione di Google Workspace Studio con i componenti aggiuntivi è in anteprima limitata. Scopri di più

Questa guida spiega come creare una variabile di input.

Per essere eseguiti, i passaggi richiedono determinate informazioni. Ad esempio, per inviare un'email è necessario un indirizzo email. Per fornire queste informazioni necessarie, definisci le variabili di input. Una volta definite, le variabili di input vengono in genere impostate dall'utente nella scheda di configurazione di un passaggio durante la configurazione del passaggio.

Definisci la variabile di input in due posizioni: nel file manifest del componente aggiuntivo e nel codice con una scheda di configurazione in cui gli utenti possono inserire i valori per le variabili di input.

Definisci la variabile di input nel file manifest

Nel file manifest, specifica le variabili di input con l'array inputs[]. Ogni elemento dell'array inputs[] ha le seguenti proprietà:

• id: identificatore univoco per una variabile di input. Per consentire al flusso di associare un elemento di input della scheda di configurazione a questa variabile di input, deve corrispondere al nome dell'elemento della scheda corrispondente.
• description: una descrizione della variabile di input da mostrare agli utenti finali.
• cardinality: Quanti valori sono consentiti. I valori possibili sono:
  • SINGLE: è consentito un solo valore.
• dataType: il tipo di valori accettati. dataType ha la proprietà basicType che definisce il tipo di dati. I valori validi includono:
  • STRING: una stringa alfanumerica.
  • INTEGER: un numero.
  • TIMESTAMP: un timestamp nel formato "millisecondi dall'epoca Unix". Ad esempio, 27 novembre 2025, 16:49:02 UTC è rappresentato come 1764262142988.
  • BOOLEAN: true o false.
  • EMAIL_ADDRESS: un indirizzo email nel formato [e-mail].

L'esempio seguente definisce tre variabili di input per un passaggio del calcolatore. Le prime due variabili di input sono numeri interi, mentre la terza è un'operazione aritmetica.

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

Definisci la variabile di input nel codice

Il codice del passaggio include una funzione chiamata onConfigFunction() che restituisce una scheda di configurazione che definisce un widget della scheda di input per ogni variabile di input definita nell'array inputs[] del file manifest.

I widget di input definiti nella scheda di configurazione hanno i seguenti requisiti:

• Il name di ogni widget di input deve corrispondere al id della variabile di input corrispondente nel file manifest.
• La cardinalità del widget di input deve corrispondere a quella della variabile di input cardinality nel file manifest.
• Il tipo di dati del widget di input deve corrispondere a dataType della variabile di input nel file manifest. Se la variabile di input ha un dataType di tipo integer, non può contenere una stringa.

Per assistenza nella creazione di interfacce delle schede, consulta una di queste opzioni:

• Il generatore di schede: uno strumento interattivo che puoi utilizzare per creare e definire le schede.
• Scheda: nella documentazione di riferimento dell'API dei componenti aggiuntivi di Google Workspace.
• Servizio schede: un servizio Apps Script che consente agli script di configurare e creare schede.
• Panoramica delle interfacce basate su schede: nella documentazione per gli sviluppatori di componenti aggiuntivi di Google Workspace.

L'esempio seguente restituisce una scheda di configurazione per ogni widget di input definito in Definisci la variabile di input nel file manifest.

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;
}

Utilizzare le variabili di output dei passaggi precedenti

Puoi configurare le variabili di input in modo che accettino le variabili di output dei passaggi precedenti nel flusso di lavoro.

Abilita la selezione delle variabili

Per consentire agli utenti di selezionare le variabili dai passaggi precedenti, utilizza la proprietà includeVariables nei widget TextInput e SelectionInput.

I widget TextInput e SelectionInput hanno queste funzionalità specifiche di Workspace Studio:

• includeVariables: una proprietà booleana che consente agli utenti di selezionare le variabili dai passaggi precedenti. Affinché il selettore di variabili venga visualizzato nei passaggi successivi, sia l'evento iniziale sia almeno una variabile di output corrispondente devono essere mappati alla variabile.
• type: un valore enumerato che completa automaticamente i suggerimenti. I valori supportati includono:
  • USER: fornisce suggerimenti di completamento automatico per le persone nei contatti dell'utente.
  • SPACE: fornisce suggerimenti di completamento automatico per gli spazi di Google Chat di cui l'utente è membro.

Quando sono impostati sia includeVariables sia type, il campo di input combina le loro esperienze. Gli utenti possono selezionare una variabile della corrispondenza type da un menu a discesa e visualizzare i suggerimenti di completamento automatico.

• 

  Figura 4: un utente esamina i suggerimenti di completamento automatico quando sceglie uno spazio.

• 

  Figura 5: un utente seleziona la variabile di output di un passaggio precedente dal menu a discesa ➕Variabili.

Nota: quando utilizzi SelectionInput con includeVariables impostato su true, devi impostare il tipo di widget su MULTI_SELECT. I menu a discesa a scelta singola non supportano l'inserimento di variabili.

Seleziona una sola variabile di output con un menu extra

Puoi configurare un widget SelectionInput per consentire agli utenti di selezionare una singola variabile di output da un passaggio precedente utilizzando un menu di overflow.

Quando imposti SelectionInputType su OVERFLOW_MENU, il widget funge da selettore di variabili dedicato. A differenza dell'utilizzo di includeVariables con TextInput, che converte i valori delle variabili in stringhe, OVERFLOW_MENU conserva il tipo di dati originale della variabile selezionata.

Apps Script

const selectionInput = CardService.newSelectionInput()
  .setFieldName("variable_picker_1")
  .setTitle("Variable Picker")
  .setType(
    CardService.SelectionInputType.OVERFLOW_MENU
  );

Consenti agli utenti di combinare variabili di testo e di output

Puoi configurare i widget TextInput per controllare il modo in cui gli utenti interagiscono con il testo e le variabili di output utilizzando setInputMode().

• RICH_TEXT: consente agli utenti di combinare variabili di testo e di output. Il risultato è una singola stringa concatenata.
• PLAIN_TEXT: limita l'input. Gli utenti possono digitare il testo o selezionare una singola variabile di output. La selezione di una variabile sostituisce qualsiasi testo esistente. Utilizza questa modalità per applicare tipi di dati specifici definiti nel manifest.

L'immagine seguente mostra due widget TextInput. Il primo è configurato come RICH_TEXT e include testo e una variabile di output. La seconda è configurata come PLAIN_TEXT e consente solo una variabile di output.

• 

  Figura 3: widget di input di testo configurati come RICH_TEXT e PLAIN_TEXT.

Ti consigliamo di impostare esplicitamente la modalità di inserimento per tutti i widget TextInput.

Ecco il file manifest per la configurazione dei widget TextInput con diverse modalità di input:

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

Ecco il codice per configurare i widget TextInput con diverse modalità di input:

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) {
}

Personalizzare i pulsanti del selettore di variabili

Puoi personalizzare il pulsante del selettore di variabili impostando le dimensioni e l'etichetta.

Dimensioni pulsante

Per impostare le dimensioni del pulsante, utilizza setVariableButtonSize() con una delle seguenti enumerazioni VariableButtonSize:

• UNSPECIFIED: il valore predefinito. Il pulsante è compatto nel riquadro laterale e a grandezza naturale in altri contesti.
• COMPACT: il pulsante mostra solo un segno più (+).
• FULL_SIZE: il pulsante mostra l'etichetta di testo completa.

Etichetta pulsante

Per impostare il testo del pulsante, utilizza setVariableButtonLabel().

Esempio: personalizzazione del selettore di variabili

L'esempio seguente mostra come configurare i widget TextInput con dimensioni diverse del pulsante di selezione delle variabili e un'etichetta personalizzata.

• 

  Figura 1: personalizzazione del pulsante del selettore di variabili sul web.

• 

  Figura 2: personalizzazione del pulsante di selezione delle variabili in un riquadro laterale del componente aggiuntivo.

Ecco il file manifest per personalizzare i pulsanti del selettore delle variabili:

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

Ecco il codice per personalizzare i pulsanti del selettore di variabili:

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) {
}

Configurare il completamento automatico dei dati di Google Workspace

Puoi anche compilare i suggerimenti di completamento automatico con i dati all'interno dell'ambiente Google Workspace dell'utente:

• Utenti di Google Workspace:popola gli utenti all'interno della stessa organizzazione Google Workspace.
• Spazi di Google Chat:popola gli spazi di Google Chat di cui l'utente è membro.

Per configurare questa impostazione, imposta PlatformDataSource nel widget SelectionInput, specificando WorkflowDataSourceType come USER o SPACE.

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)
            ))
    );

Esempio: combinazione di tipi di completamento automatico

L'esempio seguente mostra una funzione onConfig che crea una scheda con tre widget SelectionInput, che dimostrano il completamento automatico lato server, utente e spazio:

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();
}

Convalida la variabile di input

Come best practice, verifica che l'utente inserisca un valore appropriato. Consulta Convalidare una variabile di input.

Argomenti correlati

• Convalidare una variabile di input
• Variabili di output
• Variabili dinamiche
• Registrare attività ed errori
• Oggetti evento di Workspace Studio