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

Aperçu limité : l'extension de Google Workspace Studio avec des modules complémentaires est disponible en aperçu limité. En savoir plus

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 aux étapes, 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, doit correspondre au nom 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 : nombre.
  • TIMESTAMP : code temporel au format "millisecondes depuis l'époque Unix". Par exemple, le 27 novembre 2025 à 16:49:02 UTC est représenté par 1764262142988.
  • BOOLEAN : valeur "true" ou "false".
  • EMAIL_ADDRESS : adresse e-mail au format [e-mail].

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 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 fiche de configuration définissant un widget de fiche 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 fiche de configuration doivent répondre aux exigences suivantes :

• Le name de chaque widget d'entrée doit correspondre à l'id de sa 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 au 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 sur la création d'interfaces de fiche, consultez l'une des options suivantes :

• Card Builder : outil interactif que vous pouvez utiliser pour créer et définir des fiches.
• Fiche : dans la documentation de référence de l'API de module complémentaire Google Workspace documentation.
• Service de fiche : 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 des variables de sortie à partir d'étapes précédentes

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

Activer la sélection de 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 présentent les fonctionnalités spécifiques à Workspace Studio suivantes :

• includeVariables: propriété booléenne qui permet aux utilisateurs de sélectionner des variables à partir d'étapes précédentes. Pour que le sélecteur de variables s'affiche lors des étapes ultérieures, l' événement de démarrage 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 de saisie 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 semi-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.

Remarque : Lorsque vous utilisez SelectionInput avec includeVariables défini sur true, vous devez définir le type de widget sur MULTI_SELECT. Les menus déroulants à sélection unique ne sont pas compatibles avec l'injection de variables.

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

Vous pouvez configurer un SelectionInput widget 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 TextInput widgets pour contrôler la manière dont les utilisateurs interagissent avec le texte et 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 seule chaîne concaténée.
• PLAIN_TEXT: limite l'entrée. Les utilisateurs peuvent saisir du texte ou sélectionner une seule variable de sortie. La sélection d'une variable remplace tout texte existant. 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. Le premier est configuré en tant que 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 pour configurer les widgets TextInput avec différents modes d'entrée :

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 pour configurer les widgets TextInput avec différents modes d'entrée :

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 d'autres contextes.
• COMPACT : le bouton n'affiche qu'un signe plus (+).
• FULL_SIZE : le bouton affiche le libellé de texte complet.

Libellé du bouton

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

Exemple : Personnalisation du sélecteur de variables

L'exemple suivant montre comment configurer des widgets TextInput avec différentes tailles de boutons de sélecteur 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 pour 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 pour 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 des suggestions de saisie semi-automatique à partir de 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 le PlatformDataSource dans le widget SelectionInput, en spécifiant le WorkflowDataSourceType comme 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 SelectionInput widgets, illustrant la saisie semi-automatique 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 la section Valider une variable d'entrée.

Articles associés

• Valider une variable d'entrée
• Variables de sortie
• Variables dynamiques
• Consigner l'activité et les erreurs
• Objets d'événement Workspace Studio