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 ISO 8601. Par exemple, dans la norme ISO 8601, le 15 mars 2025 est représenté par 2025-03-15.
    • BOOLEAN : "true" ou "false".
    • 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": "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"
          }
        }
      ]
    }
  }
}

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

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.