Cette page a été traduite par l'API Cloud Translation.

Guide de démarrage rapide : créer une étape de calculatrice avec Google Apps Script

Ce guide de démarrage rapide vous explique comment créer une étape personnalisée pour Workspace Studio à l'aide de Google Apps Script. L'étape personnalisée prend deux nombres et une opération arithmétique en entrée, effectue le calcul et renvoie le résultat.

Un utilisateur configure l'étape du calculateur dans un agent.

Figure 1 : Un utilisateur configure l'étape du calculateur dans un agent.

Objectifs

Créez une étape personnalisée pour Workspace Studio avec Google Apps Script.
Déployez l'étape personnalisée dans votre propre organisation Google Workspace.
Testez l'étape personnalisée dans Workspace Studio.

Prérequis

Un compte Google ayant accès à Workspace Studio.

Configurer le script

Pour configurer le script, créez un projet Apps Script, puis associez-le à votre projet Cloud.

Cliquez sur le bouton suivant pour ouvrir le projet Apps Script Démarrage rapide du calculateur.

Ouvrir le projet
Cliquez sur Vue d'ensemble.
Sur la page "Vue d'ensemble", cliquez sur Créer une copie.
Nommez votre copie du projet Apps Script :
1. Cliquez sur Copie du guide de démarrage rapide du simulateur de coût.
2. Dans le champ Titre du projet, saisissez Calculator quickstart.
3. Cliquez sur Renommer.

Facultatif : Examiner le code du démarrage rapide

Dans la section précédente, vous avez copié un projet Apps Script entier contenant tout le code d'application requis pour l'étape personnalisée de votre agent. Vous n'avez donc pas besoin de copier et coller chaque fichier.

Si vous le souhaitez, vous pouvez examiner chaque fichier que vous avez copié dans la section précédente :

appsscript.json

Fichier manifeste. Fichier JSON spécial qui spécifie des informations de base sur le projet dont Apps Script a besoin pour exécuter le script.

Afficher le code `appsscript.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": "onConfigCalculateFunction",
            "onExecuteFunction": "onExecuteCalculateFunction"
          }
        }
      ]
    }
  }
}

Calculator.gs

Définit une étape personnalisée pour Google Workspace Studio. L'étape "Calculer" prend deux nombres et une opération comme entrée, puis renvoie le résultat du calcul.

Afficher le code `Calculator.gs`

/**
 * This script defines a custom step for Google Workspace Studio.
 * The step, named "Calculate", takes two numbers and an operation as input
 * and returns the result of the calculation.
 *
 * The script includes functions to:
 *
 * 1.  Define the configuration UI for the step using Card objects:
 *
 *     - `onConfigCalculateFunction()`: Generates the main configuration card.
 *     - Helper functions like `pushCard()`, `saveButton()` to build card components.
 *
 * 2.  Handle the execution of the step.
 *
 *     - `onExecuteCalculateFunction()`: Retrieves inputs, performs the calculation,
 *       and returns outputs.
 *
 * To learn more, see the following quickstart guide:
 * https://developers.google.com/workspace/add-ons/studio/quickstart
 */

/**
 * Creates an action response to push a new card onto the card stack.
 *
 * This function generates an action object that, when returned, causes the
 * provided card to be pushed onto the card stack, making it the currently
 * displayed card in the configuration UI.
 * @param {Object} card The Card object to push.
 * @return {Object} The action response object.
 */
function pushCard(card) {
  return {

      "action": {
        "navigations": [{
            "push_card": card
          }
        ]
      }  };  
}

/**
 * Creates an action response to update the currently displayed card.
 *
 * This function generates an action object that, when returned, causes the
 * currently displayed card to be replaced with the provided card in the
 * configuration UI.
 * @param {Object} card The Card object to update.
 * @return {Object} The render actions object.
 */
function updateCard(card) {
  return {
    "render_actions": {
      "action": {
        "navigations": [{
            "update_card": card
          }
        ]
      }
    }
  };
}

/**
 * Creates a button configuration object for saving the step.
 *
 * This function generates a button definition that, when clicked, triggers
 * a save action for the current step configuration.
 * @return {Object} The button widget object.
 */
function saveButton() {
  return {
      "text": "Save",
      "onClick": {
        "hostAppAction" : {
          "workflowAction" : {
            "saveWorkflowAction" : {}
          }
        }
      },
    };
}

/**
 * Creates a button configuration object for a refresh action.
 *
 * This function generates a button definition that, when clicked, triggers
 * a function to refresh the current card.
 * @param {string} functionName The name of the Apps Script function to call on click.
 * @return {Object} The button widget object.
 */
function refreshButton(functionName) {
  return {
      "text": "Refresh",
      "onClick": {
        "action" : {
          "function" : functionName
        }
      },
    };
}


/**
 * Generates and displays a configuration card for the sample calculation action.
 *
 * This function creates a card with input fields for two values and a dropdown
 * for selecting an arithmetic operation. The card also includes a "Save"
 * button to save the action configuration for the step.
 *
 * The input fields are configured to let the user select outputs from previous
 * steps as input values using the `hostAppDataSource` property.
 * This function is called when the user adds or edits the "Calculate" step in the UI.
 * @return {Object} The action response object containing the card to display.
 */
function onConfigCalculateFunction() {
  var card = {
    "sections": [
      {
        "header": "Action sample: Calculate",
        "widgets": [
          {
            "textInput": {
              "name": "value1",
              "label": "First value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          },
          {
            "selectionInput": {
              "name": "operation",
              "label": "Operation",
              "type": "DROPDOWN",
              "items": [
                {
                  "text": "+",
                  "value": "+",
                },
                {
                  "text": "-",
                  "value": "-",
                },
                {
                  "text": "x",
                  "value": "x",
                },
                {
                  "text": "/",
                  "value": "/",
                }
              ]
            }
          },
          {
            "textInput": {
              "name": "value2",
              "label": "Second value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          }
        ]
      }
    ]
  };
  return pushCard(card);
}

/**
 * Gets an integer value from variable data, handling both string and integer formats.
 *
 * This function attempts to extract an integer value from the provided variable data.
 * It checks if the data contains string values and, if so, parses the first string
 * as an integer. If integer values are present, it returns the first integer.
 * @param {Object} variableData The variable data object from the event.
 * @return {number} The extracted integer value.
 */
function getIntValue(variableData) {
  if (variableData.stringValues) {
    return parseInt(variableData.stringValues[0]);
  }
  return variableData.integerValues[0];
}

/**
* Returns output variables from a step.
*
* This function constructs an object that, when returned, sends the
* provided variable values as output from the current step.
* The variable values are logged to the console for debugging purposes.
*/
function outputVariables(variableDataMap) {
 const workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
   .setVariableDataMap(variableDataMap);

 const hostAppAction = AddOnsResponseService.newHostAppAction()
   .setWorkflowAction(workflowAction);

 const renderAction = AddOnsResponseService.newRenderActionBuilder()
   .setHostAppAction(hostAppAction)
   .build();

 return renderAction;
}

/**
 * Executes the calculation action based on the inputs from an event.
 *
 * This function retrieves input values ("value1", "value2") and the "operation"
 * from the event, performs the calculation, and returns the "result" and
 * "log" as output variables.
 * This function is called when the agent reaches this custom step.
 * @param {Object} event The event object passed by the runtime.
 * @return {Object} The output variables object.
 */
function onExecuteCalculateFunction(event) {
 console.log("output: " + JSON.stringify(event));
 var calculatedValue = 0;
 var value1 = event.workflow.actionInvocation.inputs["value1"].integerValues[0];
 var value2 = event.workflow.actionInvocation.inputs["value2"].integerValues[0];
 var operation = event.workflow.actionInvocation.inputs["operation"].stringValues[0];


 if (operation == "+") {
   calculatedValue = value1 + value2;
 } else if (operation == "-") {
   calculatedValue = value1 - value2;
 } else if (operation == "x") {
   calculatedValue = value1 * value2;
 } else if (operation == "/") {
   calculatedValue = value1 / value2;
 }

 const variableDataMap = { "result": AddOnsResponseService.newVariableData().addIntegerValue(calculatedValue) };

 return outputVariables(variableDataMap);
}

Déployer et tester votre étape

Pour tester votre étape, configurez un déploiement de test pour votre module complémentaire, ajoutez l'étape à un agent, puis exécutez l'agent.

Configurez un déploiement de test pour votre module complémentaire :
1. Ouvrez le projet de script dans l'éditeur Apps Script.
2. Cliquez sur Déployer > Tester les déploiements.
3. Cliquez sur Installer.
4. En bas de l'écran, cliquez sur OK.
Vous pouvez autoriser d'autres utilisateurs à tester le module complémentaire en partageant le projet Apps Script avec leur compte (l'accès en modification est requis). Demandez ensuite aux utilisateurs de suivre les étapes précédentes.

Une fois installé, le module complémentaire est immédiatement disponible dans Agents. Vous devrez peut-être actualiser les agents avant que le module complémentaire n'apparaisse. Vous devez également autoriser le module complémentaire avant de l'utiliser.

Pour en savoir plus sur les déploiements de test, consultez Installer un module complémentaire non publié.
Ouvrez Agents.
Créez un agent qui inclut votre étape :
1. Cliquez sur New agent (Nouvel agent).
2. Sélectionnez le mode de démarrage de l'agent. Lorsque vous testez une étape, choisissez un déclencheur que vous pouvez définir vous-même, comme l'envoi d'un e-mail. Si votre étape nécessite une variable d'entrée, configurez-la comme faisant partie de la sortie du starter.
3. Cliquez sur Ajouter une étape. Sélectionnez l'étape que vous avez créée ou modifiée, appelée Calculer.
4. Configurez votre étape. Pour l'étape de calcul, choisissez deux valeurs et une opération mathématique. L'étape est enregistrée automatiquement.
5. Pour tester le résultat de votre étape, ajoutez-en une autre. Par exemple, pour ajouter une sortie à un e-mail, vous pouvez ajouter l'étape Envoyer un message de Gmail. Dans Message, cliquez sur Variables, puis sélectionnez la sortie de votre étape. Pour l'étape de calcul, sélectionnez Variables > Étape 2 : Résultat calculé > Résultat calculé. La variable s'affiche sous forme de chip dans le champ Message.
6. Cliquez sur Activer. Votre agent est prêt à s'exécuter.
Exécutez l'agent en déclenchant son point de départ. Par exemple, si votre agent démarre lorsque vous recevez un e-mail, envoyez-vous un e-mail.
Vérifiez que l'agent s'exécute comme prévu. Consultez les journaux en accédant à l'onglet Activité du créateur d'agents. Pour savoir comment créer des journaux personnalisés dans l'onglet "Activité", consultez Journaux d'activité.

Étapes suivantes

Vous avez créé et testé une étape personnalisée pour Workspace Studio. Vous pouvez à présent :

Continuez à personnaliser l'étape en demandant à Gemini de vous aider à implémenter une logique plus complexe.
Créez une fiche de configuration pour personnaliser la configuration des étapes.
Consignez l'activité et les erreurs pour enregistrer et résoudre les problèmes liés à l'exécution de vos étapes.
Examinez les objets d'événement pour consulter la charge utile JSON que les agents envoient et reçoivent lors de l'exécution des étapes.

Guide de démarrage rapide : créer une étape de calculatrice avec Google Apps Script Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.