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

Créer une étape

Ce guide explique comment créer une étape que les utilisateurs peuvent ajouter à un agent dans Google Workspace Studio.

Une étape correspond à une étape unique dans la séquence de tâches d'un agent. Les étapes ne peuvent pas démarrer un agent.

Prenons l'exemple d'une étape qui effectue des calculs arithmétiques. Il demande à l'utilisateur deux valeurs et une opération mathématique. Elle effectue ensuite l'opération mathématique sur les valeurs et affiche 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.

Pour créer une étape, configurez-la dans le fichier manifeste du module complémentaire, écrivez la logique de l'application dans le code du module complémentaire Google Workspace, puis déployez et testez l'étape.

Définir l'étape

Pour configurer une étape, définissez-la dans le fichier manifeste et écrivez sa logique d'application dans le code.

Définir l'étape dans le fichier manifeste

Dans le fichier manifeste, appsscript.json :

Définissez onConfigFunction et onExecuteFunction sur les noms des fonctions correspondantes dans le code du module complémentaire. Dans cet exemple, les fonctions sont appelées onConfigCalculate() et onExecuteCalculate().
- onConfigFunction configure l'étape. Si nécessaire, collecte les données des utilisateurs nécessaires à l'exécution de l'étape, comme l'adresse à laquelle envoyer un e-mail. Dans l'exemple de ce guide, nous demandons deux valeurs et une opération mathématique.
- onExecuteFunction exécute l'étape. Si des données ont été collectées auprès des utilisateurs, elles sont transmises à cette fonction. Renvoie une sortie, le cas échéant. Dans l'exemple de ce guide, le résultat d'un calcul mathématique est affiché.
Définissez les entrées et sorties requises, ce qui permet à l'étape de collecter des données et de les envoyer aux étapes ultérieures. Dans cet exemple, demandez à l'utilisateur deux valeurs et une opération mathématique définie dans inputs[]. Affichez le résultat calculé tel que défini dans outputs[].

Pour en savoir plus sur les entrées et les sorties, consultez Variables d'entrée et Variables de sortie. Pour vous assurer que les agents s'exécutent sans erreur, validez les variables d'entrée.

Voici le fichier manifeste de l'étape "Calculatrice" :

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

Ensuite, écrivez le code d'assistance en définissant l'étape dans le code.

Définir l'étape dans le code

Dans le code de l'application, procédez comme suit :

Écrivez le onConfigFunction, appelé onConfigCalculate() dans cet exemple. Lorsque les utilisateurs ajoutent l'étape à un agent, ils peuvent configurer des aspects de l'étape dans le générateur d'agents. Pour collecter les informations requises auprès de l'utilisateur, onConfigFunction définit une fiche de configuration.

Les fiches sont les blocs de construction des interfaces utilisateur dans les modules complémentaires. Les fiches sont compatibles avec une mise en page définie, des éléments d'interface utilisateur interactifs tels que des boutons et des contenus multimédias enrichis tels que des images. Les fiches vous permettent d'obtenir des données d'un utilisateur dont l'étape a besoin pour s'exécuter, comme une adresse e-mail pour envoyer un e-mail.

OnConfigFunction renvoie une carte. Cette carte définit l'UI dans laquelle les utilisateurs définissent les données de l'étape. Dans cet exemple, onConfigFunction crée une fiche qui demande à l'utilisateur deux valeurs et une opération mathématique.
Écrivez le onExecuteFunction appelé onExecuteCalculate() dans cet exemple. Lorsque votre étape s'exécute dans un agent, OnExecuteFunction s'exécute. Toutes les valeurs d'entrée définies par l'utilisateur lors de la configuration, telles que définies dans onConfigurationFunction, sont transmises à OnExecuteFunction.

Écrivez OnExecuteFunction() pour qu'il exécute sa tâche de manière synchrone à l'aide des entrées fournies. N'oubliez pas que OnExecuteFunction() doit renvoyer toutes les sorties définies dans le fichier manifeste de votre agent. Sinon, une erreur se produit.

Cet exemple de code inclut une fonction d'assistance, outputVariables(), qui construit et envoie les variables fournies en tant que sortie de l'étape.

Votre étape est prête à être testée.

Voici le code de l'étape "Calculatrice" :

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
 * steps as input values using the `hostAppDataSource` property.
 */
function onConfigCalculate() {
  const firstInput = CardService.newTextInput()
  .setFieldName("value1")
  .setTitle("First Value")
  .setHostAppDataSource(
    CardService.newHostAppDataSource()
      .setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
      )
  );
  const secondInput = CardService.newTextInput()
    .setFieldName("value2")
    .setTitle("Second Value").setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );
  const selectionInput = CardService.newSelectionInput()
    .setTitle("operation")
    .setFieldName("operation")
    .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)

  var card = CardService.newCardBuilder()
    .addSection(sections)
    .build();

  return card;
}

/**
* 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 step based on the inputs from a flow event.
 *
 * This function retrieves input values and the operation from the flow event,
 * performs the calculation, and returns the result as an output variable.
 * The function logs the event for debugging purposes.
 */
function onExecuteCalculate(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);
}

Tester votre pas

Pour tester votre étape, configurez un déploiement 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, il est judicieux de choisir 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 à être exécuté.
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é.

Créer une étape Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.