Collecter des données avec une variable d'entrée

Ce guide explique comment créer une variable d'entrée.

Pour s'exécuter, les étapes nécessitent certaines informations. Par exemple, l'envoi d'un e-mail nécessite une adresse e-mail. Pour fournir ces informations nécessaires, définissez des variables d'entrée. Une fois définies, les variables d'entrée sont généralement définies par l'utilisateur sur la fiche de configuration d'une étape lors de la configuration de l'étape.

Définissez la variable d'entrée à deux endroits : dans le fichier manifeste du module complémentaire et dans le code avec une fiche de configuration où les utilisateurs peuvent saisir des valeurs pour les variables d'entrée.

Définir la variable d'entrée dans le fichier manifeste

Dans le fichier manifeste, spécifiez les variables d'entrée avec le tableau inputs[]. Chaque élément du tableau inputs[] possède les propriétés suivantes :

id : identifiant unique d'une variable d'entrée. Pour permettre au flux d'associer un élément d'entrée de fiche de configuration à cette variable d'entrée, le nom doit correspondre à celui de l'élément de fiche correspondant.
description : description de la variable d'entrée à afficher aux utilisateurs finaux.
cardinality : nombre de valeurs autorisées. Les valeurs possibles sont les suivantes :
- SINGLE : une seule valeur est autorisée.
dataType : type de valeurs acceptées. dataType possède la propriété basicType qui définit le type de données. Les valeurs valides sont les suivantes :
- STRING : chaîne alphanumérique.
- INTEGER : un nombre.
- TIMESTAMP : code temporel au format "millisecondes depuis l'epoch Unix". Par exemple, le 27 novembre 2025 à 16:49:02 UTC est représenté par 1764262142988.
- BOOLEAN : vrai ou faux.
- EMAIL_ADDRESS : adresse e-mail au format dana@example.com.

L'exemple suivant définit trois variables d'entrée pour une étape de calculatrice. Les deux premières variables d'entrée sont des nombres entiers, et la troisième est une opération arithmétique.

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

Définir la variable d'entrée dans le code

Le code de l'étape inclut une fonction appelée onConfigFunction() qui renvoie une carte de configuration définissant un widget de carte d'entrée pour chaque variable d'entrée définie dans le tableau inputs[] du fichier manifeste.

Les widgets d'entrée définis dans la carte de configuration doivent respecter les exigences suivantes :

Le name de chaque widget d'entrée doit correspondre au id de la variable d'entrée correspondante dans le fichier manifeste.
La cardinalité du widget d'entrée doit correspondre à la cardinality de la variable d'entrée dans le fichier manifeste.
Le type de données du widget d'entrée doit correspondre à la dataType de la variable d'entrée dans le fichier manifeste. Si la variable d'entrée a un dataType de type entier, elle ne peut pas contenir de chaîne.

Pour obtenir de l'aide concernant la création d'interfaces de fiches, consultez l'une des options suivantes :

Card Builder : outil interactif permettant de créer et de définir des fiches.
Card : dans la documentation de référence de l'API des modules complémentaires Google Workspace.
Card Service : service Apps Script qui permet aux scripts de configurer et de créer des fiches.
Présentation des interfaces basées sur des fiches : dans la documentation destinée aux développeurs de modules complémentaires Google Workspace.

L'exemple suivant renvoie une fiche de configuration pour chaque widget d'entrée défini dans Définir la variable d'entrée dans le fichier manifeste.

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

Utiliser les variables de sortie des étapes précédentes

Vous pouvez configurer des variables d'entrée pour accepter les variables de sortie des étapes précédentes du workflow.

Activer la sélection des variables

Pour permettre aux utilisateurs de sélectionner des variables à partir d'étapes précédentes, utilisez la propriété includeVariables dans les widgets TextInput et SelectionInput.

Les widgets TextInput et SelectionInput disposent des fonctionnalités spécifiques à Workspace Studio suivantes :

includeVariables : propriété booléenne qui permet aux utilisateurs de sélectionner des variables à partir des étapes précédentes. Pour que le sélecteur de variables s'affiche lors des étapes ultérieures, l'événement de départ et au moins une variable de sortie correspondante doivent être mappés à la variable.
type : valeur énumérée qui complète automatiquement les suggestions. Les valeurs acceptées sont les suivantes :
- USER : fournit des suggestions de saisie semi-automatique pour les personnes figurant dans les contacts de l'utilisateur.
- SPACE : fournit des suggestions de saisie semi-automatique pour les espaces Google Chat dont l'utilisateur est membre.

Lorsque includeVariables et type sont définis, le champ d'entrée combine leurs expériences. Les utilisateurs peuvent sélectionner une variable du type correspondant dans un menu déroulant et voir des suggestions de saisie automatique.

Figure 4 : Un utilisateur examine les suggestions de saisie semi-automatique lorsqu'il choisit un espace.
Figure 5 : Un utilisateur sélectionne la variable de sortie d'une étape précédente dans le menu déroulant ➕ Variables.

Sélectionner une seule variable de sortie avec un menu à développer

Vous pouvez configurer un widget SelectionInput pour permettre aux utilisateurs de sélectionner une seule variable de sortie à partir d'une étape précédente à l'aide d'un menu à développer.

Lorsque vous définissez SelectionInputType sur OVERFLOW_MENU, le widget sert de sélecteur de variables dédié. Contrairement à l'utilisation de includeVariables avec TextInput, qui convertit les valeurs de variables en chaînes, OVERFLOW_MENU conserve le type de données d'origine de la variable sélectionnée.

Apps Script

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

Permettre aux utilisateurs de combiner du texte et des variables de sortie

Vous pouvez configurer des widgets TextInput pour contrôler la façon dont les utilisateurs interagissent avec le texte et les variables de sortie à l'aide de setInputMode().

RICH_TEXT : permet aux utilisateurs de combiner du texte et des variables de sortie. Le résultat est une chaîne concaténée unique.
PLAIN_TEXT : restreint l'entrée. Les utilisateurs peuvent saisir du texte ou sélectionner une seule variable de sortie. Si vous sélectionnez une variable, tout texte existant est remplacé. Utilisez ce mode pour appliquer des types de données spécifiques définis dans le fichier manifeste.

L'image suivante montre deux widgets TextInput. La première est configurée comme RICH_TEXT et comporte du texte et une variable de sortie. Le second est configuré en tant que PLAIN_TEXT et n'autorise qu'une variable de sortie.

Figure 3 : Widgets de saisie de texte configurés en tant que RICH_TEXT et PLAIN_TEXT.

Nous vous recommandons de définir explicitement le mode d'entrée pour tous les widgets TextInput.

Voici le fichier manifeste permettant de configurer les widgets TextInput avec différents modes de saisie :

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

Voici le code permettant de configurer les widgets TextInput avec différents modes de saisie :

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

Personnaliser les boutons du sélecteur de variables

Vous pouvez personnaliser le bouton du sélecteur de variables en définissant sa taille et son libellé.

Taille du bouton

Pour définir la taille du bouton, utilisez setVariableButtonSize() avec l'une des énumérations VariableButtonSize suivantes :

UNSPECIFIED : valeur par défaut. Le bouton est compact dans le panneau latéral et en taille réelle dans les autres contextes.
COMPACT : le bouton n'affiche qu'un signe plus (+).
FULL_SIZE : le bouton affiche le libellé de texte complet.

Texte du bouton

Pour définir le texte du bouton, utilisez setVariableButtonLabel().

Exemple de personnalisation du sélecteur de variables

L'exemple suivant montre comment configurer des widgets TextInput avec différentes tailles de bouton de sélection de variables et un libellé personnalisé.

Figure 1 : Personnalisation du bouton du sélecteur de variables sur le Web.
Figure 2 : Personnalisation du bouton du sélecteur de variables dans un panneau latéral de module complémentaire.

Voici le fichier manifeste permettant de personnaliser les boutons du sélecteur de variables :

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

Voici le code permettant de personnaliser les boutons du sélecteur de variables :

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

Configurer la saisie semi-automatique des données Google Workspace

Vous pouvez également remplir les suggestions de saisie semi-automatique à partir des données de l'environnement Google Workspace de l'utilisateur :

Utilisateurs Google Workspace : remplissez les utilisateurs de la même organisation Google Workspace.
Espaces Google Chat : remplissez les espaces Google Chat dont l'utilisateur est membre.

Pour configurer cela, définissez PlatformDataSource dans le widget SelectionInput, en spécifiant WorkflowDataSourceType sur USER ou 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)
            ))
    );

Exemple : Combiner des types de saisie semi-automatique

L'exemple suivant montre une fonction onConfig qui crée une fiche avec trois widgets SelectionInput, illustrant l'autocomplete côté serveur, utilisateur et espace :

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

Valider la variable d'entrée

Nous vous recommandons de vérifier que l'utilisateur saisit une valeur appropriée. Consultez Valider une variable d'entrée.

Collecter des données avec une variable d'entrée Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Définir la variable d'entrée dans le fichier manifeste

JSON

Définir la variable d'entrée dans le code

Apps Script

Utiliser les variables de sortie des étapes précédentes

Activer la sélection des variables

Sélectionner une seule variable de sortie avec un menu à développer

Apps Script

Permettre aux utilisateurs de combiner du texte et des variables de sortie

JSON

Apps Script

Personnaliser les boutons du sélecteur de variables

Taille du bouton

Texte du bouton

Exemple de personnalisation du sélecteur de variables

JSON

Apps Script

Configurer la saisie semi-automatique des données Google Workspace

Apps Script

Exemple : Combiner des types de saisie semi-automatique

JSON

Apps Script

Valider la variable d'entrée

Articles associés

Collecter des données avec une variable d'entrée