Kurzanleitung: Berechnungsschritt mit Google Apps Script erstellen

In dieser Kurzanleitung erfahren Sie, wie Sie mit Google Apps Script einen benutzerdefinierten Schritt für Workspace Studio erstellen. Der benutzerdefinierte Schritt verwendet zwei Zahlen und eine arithmetische Operation als Eingabe, führt die Berechnung aus und gibt das Ergebnis aus.

Die Karte für den Workspace Studio-Rechnerschritt mit zwei Eingabefeldern für Zahlen und einem Drop-down-Menü für arithmetische Operationen.
Abbildung 1: Ein Nutzer konfiguriert den Schritt „Rechner“ als Teil eines Flows.

Ziele

  • Mit Google Apps Script einen benutzerdefinierten Schritt für Workspace Studio erstellen
  • Den benutzerdefinierten Schritt in Ihrer eigenen Google Workspace-Organisation bereitstellen
  • Den benutzerdefinierten Schritt in Workspace Studio testen

Vorbereitung

  • Ein Google-Konto mit Zugriff auf Workspace Studio

Script einrichten

Richten Sie das Script ein, indem Sie ein neues Apps Script-Projekt erstellen und es dann mit Ihrem Cloud-Projekt verbinden.

  1. Klicken Sie auf die folgende Schaltfläche, um das Apps Script-Projekt Calculator quickstart (Schnellstart für Rechner) zu öffnen.

    Projekt öffnen

  2. Klicken Sie auf Übersicht.

  3. Klicken Sie auf der Übersichtsseite auf Symbol zum Erstellen einer Kopie Kopie erstellen.

  4. Geben Sie einen Namen für Ihre Kopie des Apps Script-Projekts ein:

    1. Klicken Sie auf Copy of Calculator quickstart (Kopie von Schnellstart für Rechner).

    2. Geben Sie unter Project title (Projekttitel) Calculator quickstart ein.

    3. Klicken Sie auf Rename (Umbenennen).

Optional: Schnellstartcode überprüfen

Im vorherigen Abschnitt haben Sie ein ganzes Apps Script-Projekt kopiert, das den gesamten erforderlichen Anwendungscode für den benutzerdefinierten Schritt Ihres Flows enthält. Sie müssen also nicht jede Datei kopieren und einfügen.

Optional können Sie hier jede Datei überprüfen, die Sie im vorherigen Abschnitt kopiert haben:

appsscript.json

Die Manifestdatei. Eine spezielle JSON-Datei, die grundlegende Projektinformationen enthält, die Apps Script zum Ausführen des Scripts benötigt.

appsscript.json-Code ansehen

{
  "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

Definiert einen benutzerdefinierten Schritt für Google Workspace Studio. Der Schritt mit dem Namen „Calculate“ (Berechnen) verwendet zwei Zahlen und eine Operation als Eingabe und gibt das Ergebnis der Berechnung zurück.

Calculator.gs-Code ansehen

/**
 * 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 flow 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);
}

Schritt bereitstellen und testen

Wenn Sie Ihren Schritt testen möchten, richten Sie eine Testbereitstellung für Ihr Add-on ein, fügen Sie den Schritt einem Flow hinzu und führen Sie den Flow dann aus.

  1. Testbereitstellung für Ihr Add-on einrichten:

    1. Öffnen Sie das Script-Projekt im Apps Script-Editor.
    2. Klicken Sie auf Deploy (Bereitstellen) > Test deployments (Testbereitstellungen).
    3. Klicken Sie auf Install (Installieren).
    4. Klicken Sie unten auf Done (Fertig).

    Sie können andere Nutzer das Add-on testen lassen, indem Sie das Apps Script-Projekt für ihr Konto freigeben (Bearbeitungszugriff ist erforderlich). Fordern Sie die Nutzer dann auf, die vorherigen Schritte auszuführen.

    Nach der Installation ist das Add-on sofort in Flows verfügbar. Möglicherweise müssen Sie Flows aktualisieren, bevor das Add-on angezeigt wird. Sie müssen das Add-on auch autorisieren, bevor Sie es verwenden können.

    Weitere Informationen zu Testbereitstellungen finden Sie unter Nicht veröffentlichtes Add-on installieren.

  2. Öffnen Sie Flows.

  3. Erstellen Sie einen Flow, der Ihren Schritt enthält:

    1. Klicken Sie auf Neuer Flow.
    2. Wählen Sie aus, wie der Flow gestartet werden soll. Wenn für Ihren Schritt eine Eingabevariable erforderlich ist, konfigurieren Sie die Eingabevariable als Teil der Ausgabe des Auslösers.
    3. Klicken Sie auf „Hinzufügen“ Schritt hinzufügen. Wählen Sie den Schritt aus, den Sie erstellt oder aktualisiert haben, mit dem Namen Calculate (Berechnen).
    4. Konfigurieren Sie den Schritt. Wählen Sie für den Schritt „Berechnen“ zwei Werte und eine mathematische Operation aus. Der Schritt wird automatisch gespeichert.
    5. Wenn Sie die Ausgabe Ihres Schritts testen möchten, fügen Sie einen weiteren Schritt hinzu. Wenn Sie beispielsweise einer Google Chat-Nachricht eine Ausgabe hinzufügen möchten, fügen Sie den Schritt Mich in Google Chat benachrichtigen von Chat hinzu. Klicken Sie unter Message (Nachricht) auf „Hinzufügen“ Variables und wählen Sie die Ausgabe Ihres Schritts aus. Wählen Sie für den Schritt „Berechnen“ die Option „Hinzufügen“ Variablen > Step 2: Calculate (Schritt 2: Berechnen) > Calculated result (Berechnetes Ergebnis) aus. Die Variable wird als Chip im Feld Message (Nachricht) angezeigt.
    6. Klicken Sie auf Aktivieren. Der Flow kann jetzt ausgeführt werden.

  4. Führen Sie den Flow aus, indem Sie den Auslöser des Flows auslösen. Wenn Ihr Flow beispielsweise nach Zeitplan gestartet wird, wird er zum angegebenen Datum und zur angegebenen Uhrzeit ausgeführt.

  5. Prüfen Sie, ob der Flow wie erwartet ausgeführt wird. Prüfen Sie die Logs auf dem Tab Aktivität des Flow-Builders. Informationen zum Erstellen benutzerdefinierter Logs auf dem Tab „Aktivität“ finden Sie unter Aktivitätslogs.

Nächste Schritte

Sie haben jetzt einen benutzerdefinierten Schritt für Workspace Studio erstellt und getestet. Du hast nun folgende Möglichkeiten: