Raccogliere dati con una variabile di input

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 in formato ISO 8601. Ad esempio, in ISO 8601, il 15 marzo 2025 è rappresentato come 2025-03-15.
    • BOOLEAN: true o false.
    • EMAIL_ADDRESS: Un indirizzo email nel formato dana@example.com.

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

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 Card: 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 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
      }]
    }
  };
}

Convalida la variabile di input

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