Krótkie wprowadzenie: tworzenie kroku kalkulatora za pomocą Google Apps Script

Z tego krótkiego wprowadzenia dowiesz się, jak utworzyć niestandardowy krok w Workspace Studio za pomocą Google Apps Script. Niestandardowy krok przyjmuje jako dane wejściowe 2 liczby i operację arytmetyczną, wykonuje obliczenia i zwraca wynik.

Karta kroku kalkulatora w Workspace Studio z 2 polami wprowadzania liczb i menu operacji arytmetycznych.
Rysunek 1: użytkownik konfiguruje krok kalkulatora w ramach automatyzacji.

Cele

  • Utworzenie niestandardowego kroku w Workspace Studio za pomocą Google Apps Script.
  • Wdrożenie niestandardowego kroku w organizacji Google Workspace.
  • Przetestowanie niestandardowego kroku w Workspace Studio.

Wymagania wstępne

  • Konto Google z dostępem do Workspace Studio.

Konfigurowanie skryptu

Aby skonfigurować skrypt, utwórz nowy projekt Apps Script, a następnie połącz go z projektem w chmurze.

  1. Kliknij ten przycisk, aby otworzyć projekt Apps Script Kalkulator – szybki start.

    Otwórz projekt

  2. Kliknij Przegląd.

  3. Na stronie przeglądu kliknij Ikona tworzenia kopii Utwórz kopię.

  4. Nazwij kopię projektu Apps Script:

    1. Kliknij Kopia Kalkulator – szybki start.

    2. W polu Tytuł projektu wpisz Calculator quickstart.

    3. Kliknij Zmień nazwę.

Opcjonalnie: sprawdź kod szybkiego startu

W poprzedniej sekcji skopiowano cały projekt Apps Script, który zawiera cały wymagany kod aplikacji dla niestandardowego kroku automatyzacji, więc nie trzeba kopiować i wklejać każdego pliku.

Opcjonalnie możesz sprawdzić każdy plik skopiowany w poprzedniej sekcji:

appsscript.json

Plik manifestu. Specjalny plik JSON, który określa podstawowe informacje o projekcie potrzebne Apps Script do uruchomienia skryptu.

Wyświetl kod 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

Definiuje niestandardowy krok w Google Workspace Studio. Krok o nazwie „Oblicz” przyjmuje jako dane wejściowe 2 liczby i operację, a następnie zwraca wynik obliczeń.

Wyświetl kod 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 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);
}

Wdrażanie i testowanie kroku

Aby przetestować krok, skonfiguruj wdrożenie testowe dodatku, dodaj krok do automatyzacji, a następnie uruchom automatyzację.

  1. Skonfiguruj wdrożenie testowe dodatku:

    1. Otwórz projekt skryptu w edytorze skryptów Apps Script.
    2. Kliknij Wdróż > Wdrożenia testowe.
    3. Kliknij Zainstaluj.
    4. U dołu kliknij Gotowe.

    Możesz umożliwić innym użytkownikom testowanie dodatku, udostępniając im projekt Apps Script (wymagany jest dostęp do edycji). Następnie poproś użytkowników o wykonanie opisanych powyżej czynności.

    Po zainstalowaniu dodatek jest natychmiast dostępny w sekcji Automatyzacje. Zanim dodatek się pojawi, może być konieczne odświeżenie sekcji Automatyzacje. Przed użyciem dodatku musisz też go autoryzować.

    Więcej informacji o wdrożeniach testowych znajdziesz w artykule Instalowanie nieopublikowanego dodatku.

  2. Otwórz sekcję Automatyzacje.

  3. Utwórz automatyzację, która zawiera Twój krok:

    1. Kliknij Nowa automatyzacja.
    2. Wybierz sposób uruchamiania automatyzacji. Jeśli Twój krok wymaga zmiennej wejściowej, skonfiguruj ją w ramach danych wyjściowych elementu uruchamiającego.
    3. Kliknij Dodaj krok. Wybierz utworzony lub zaktualizowany krok o nazwie Oblicz.
    4. Skonfiguruj krok. W przypadku kroku obliczania wybierz 2 wartości i operację matematyczną. Krok zapisze się automatycznie.
    5. Aby przetestować dane wyjściowe kroku, dodaj kolejny krok. Aby na przykład dodać dane wyjściowe do wiadomości na czacie w Google Chat, dodaj krok Powiadom mnie w Google Chat. W polu Wiadomość kliknij Zmienne i wybierz dane wyjściowe kroku. W przypadku kroku obliczania kliknij Zmienne > Krok 2: Oblicz > Wynik obliczeń. Zmienna pojawi się jako element w polu Wiadomość.
    6. Kliknij Włącz. Automatyzacja jest gotowa do uruchomienia.

  4. Uruchom automatyzację, aktywując jej element uruchamiający. Jeśli na przykład automatyzacja rozpoczyna się według harmonogramu, zostanie uruchomiona w określonym dniu i o określonej godzinie.

  5. Sprawdź, czy automatyzacja działa zgodnie z oczekiwaniami. Sprawdź logi, otwierając kartę Aktywność w kreatorze automatyzacji. Aby dowiedzieć się, jak tworzyć niestandardowe logi na karcie Aktywność, przeczytaj artykuł Dzienniki aktywności.

Dalsze kroki

Udało Ci się utworzyć i przetestować niestandardowy krok w Workspace Studio. Teraz możesz: