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. Krok niestandardowy przyjmuje jako dane wejściowe 2 liczby i operację arytmetyczną, wykonuje obliczenia i zwraca wynik.

Cele

• Utwórz niestandardowy krok dla Workspace Studio za pomocą Google Apps Script.
• Wdróż krok niestandardowy w organizacji Google Workspace.
• Przetestuj niestandardowy krok 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 i dodaj kod z krótkiego wprowadzenia:

1. Kliknij przycisk poniżej, aby utworzyć nowy projekt Apps Script:

   Tworzenie projektu

2. Nazwij projekt Apps Script:

   1. Kliknij Projekt bez nazwy.

   2. W polu Tytuł projektu wpisz Calculator quickstart.

   3. Kliknij Zmień nazwę.

3. Obok pliku Code.gs kliknij Więcej more_vert > Zmień nazwę. Nazwij plik Calculator.

4. Zastąp zawartość pliku Calculator.gs poniższym kodem. Ten plik definiuje niestandardowy krok w Google Workspace Studio o nazwie „Calculate”, który przyjmuje 2 liczby i operację jako dane wejściowe i 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);
   }

5. Kliknij Ustawienia projektu settings i zaznacz pole wyboru Pokaż plik manifestu „appsscript.json” w edytorze.

6. Kliknij Edytor code, otwórz plik manifestu appsscript.json i zastąp jego zawartość tym kodem:

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

7. Kliknij Zapisz save.

Wdrażanie i testowanie kroku

Aby przetestować krok, skonfiguruj wdrożenie testowe dodatku, dodaj krok do przepływu, a następnie uruchom przepływ.

1. Skonfiguruj wdrożenie testowe dodatku:

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

   Możesz pozwolić innym użytkownikom na testowanie dodatku, udostępniając projekt Apps Script na ich kontach (wymagane są uprawnienia do edycji). Następnie poproś użytkowników o wykonanie opisanych powyżej czynności.

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

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

2. Otwórz Flows.

3. Utwórz przepływ, który zawiera Twój krok:

   1. Kliknij add New flow (Nowy przepływ).
   2. Wybierz sposób uruchamiania automatyzacji. Jeśli krok wymaga zmiennej wejściowej, skonfiguruj ją jako część danych wyjściowych elementu inicjującego.
   3. Kliknij addDodaj krok. Wybierz utworzony lub zaktualizowany krok o nazwie Calculate (Oblicz).
   4. Skonfiguruj działanie. W kroku obliczania wybierz 2 wartości i operację matematyczną. Krok zostanie zapisany 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 sekcji Wiadomość kliknij addZmienne i wybierz dane wyjściowe kroku. W kroku obliczania wybierz addZmienne > Krok 2. Oblicz > Obliczony wynik. Zmienna pojawi się jako element w polu Wiadomość.
   6. Kliknij Włącz. Przepływ jest gotowy do uruchomienia.

4. Uruchom proces, aktywując jego polecenie inicjujące. Jeśli na przykład przepływ rozpoczyna się zgodnie z harmonogramem, zostanie uruchomiony w określonym dniu i o określonej godzinie.

5. Sprawdź, czy przepływ działa zgodnie z oczekiwaniami. Sprawdź logi na karcie Aktywność w Kreatorze przepływów. Aby dowiedzieć się, jak tworzyć niestandardowe dzienniki na karcie Aktywność, przeczytaj artykuł Historia aktywności.

Dalsze kroki

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

• Kontynuuj dostosowywanie kroku, prosząc Gemini o pomoc we wdrożeniu bardziej złożonej logiki.

• Utwórz kartę konfiguracji, aby dostosować konfigurację kroku.

• Rejestruj aktywność i błędy, aby zapisywać i rozwiązywać problemy z uruchomieniami kroków.

• Przejrzyj obiekty zdarzeń, aby sprawdzić ładunek JSON, który przepływy wysyłają i odbierają podczas wykonywania kroków.

• Wypróbuj ćwiczenie z programowania Tworzenie niestandardowych elementów wyzwalających i kroków działania w Workspace Studio, aby utworzyć niestandardowy element wyzwalający i niestandardowy krok za pomocą Apps Script.