Tworzenie kroku

Z tego przewodnika dowiesz się, jak utworzyć krok, który użytkownicy mogą dodać do automatyzacji w Google Workspace Studio.

Krok to pojedyncza czynność w sekwencji zadań automatyzacji. Kroki nie mogą uruchamiać automatyzacji.

Rozważmy na przykład krok, który wykonuje działania arytmetyczne. Prosi on użytkownika o podanie 2 wartości i działania matematycznego. Następnie wykonuje działanie matematyczne na tych wartościach i wyświetla wynik.

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

Aby utworzyć krok, skonfiguruj go w pliku manifestu dodatku, napisz logikę aplikacji w kodzie dodatku do Google Workspace, a następnie wdróż i przetestuj krok.

Definiowanie kroku

Aby skonfigurować krok, zdefiniuj go w pliku manifestu i napisz jego logikę aplikacji w kodzie.

Definiowanie kroku w pliku manifestu

W pliku manifestu appsscript.json:

  1. Ustaw onConfigFunction i onExecuteFunction na nazwy odpowiednich funkcji w kodzie dodatku. W tym przykładzie funkcje nazywają się onConfigCalculate i onExecuteCalculate.
    • onConfigFunction konfiguruje krok. W razie potrzeby zbiera od użytkowników dane niezbędne do wykonania kroku, np. adres e-mail, na który ma zostać wysłana wiadomość. W przykładzie z tego przewodnika określ 2 wartości i działanie matematyczne.
    • onExecuteFunction wykonuje krok. Jeśli dane zostały zebrane od użytkowników, są one przekazywane do tej funkcji. W stosownych przypadkach zwraca dane wyjściowe. W przykładzie z tego przewodnika zwraca wynik obliczenia matematycznego.

  2. Ustaw wymagane dane wejściowe i wyjściowe, co umożliwi krokowi zbieranie danych i wysyłanie ich do kolejnych kroków. W tym przykładzie poproś użytkownika o podanie 2 wartości i działania matematycznego zdefiniowanego w inputs[]. Wyświetl wynik obliczeń zgodnie z definicją w outputs[].

    Więcej informacji o danych wejściowych i wyjściowych znajdziesz w sekcjach Zmienne wejściowe i Zmienne wyjściowe. Aby mieć pewność, że automatyzacje działają bez błędów, sprawdź poprawność zmiennych wejściowych.

Oto plik manifestu kroku Kalkulator:

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
    },
    "studio": {
      "flows": {
        "workflowElements": [
          {
            "id": "calculatorDemo",
            "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"
            }
          }
        ]
      }
    }
  }
}

Następnie napisz kod pomocniczy, definiując krok w kodzie.

Definiowanie kroku w kodzie

W kodzie aplikacji wykonaj te czynności:

  1. Napisz onConfigFunction, która w tym przykładzie nazywa się onConfigCalculate. Gdy użytkownicy dodadzą krok do automatyzacji, będą mogli skonfigurować jego aspekty w narzędziu do tworzenia automatyzacji. Aby zebrać wymagane informacje od użytkownika, onConfigFunction definiuje kartę konfiguracji.

    Karty to elementy składowe interfejsów użytkownika w dodatkach. Karty obsługują zdefiniowany układ, interaktywne elementy interfejsu, takie jak przyciski, oraz rich media, np. obrazy. Karty umożliwiają uzyskanie od użytkownika danych, które są potrzebne do wykonania kroku, np. adresu e-mail do wysłania wiadomości.

    onConfigFunction zwraca kartę. Ta karta definiuje interfejs, w którym użytkownicy ustawiają dane kroku. W tym przykładzie onConfigFunction tworzy kartę, która prosi użytkownika o podanie 2 wartości i działania matematycznego.

  2. Napisz onExecuteFunction, która w tym przykładzie nazywa się onExecuteCalculate. Gdy Twój krok jest wykonywany w ramach automatyzacji, uruchamia się onExecuteFunction. Wszystkie wartości wejściowe ustawione przez użytkownika podczas konfiguracji zgodnie z definicją w onConfigFunction są przekazywane do onExecuteFunction.

    Napisz onExecuteFunction tak, aby synchronicznie wykonywała swoje zadanie przy użyciu podanych danych wejściowych. onExecuteFunction musi zwracać wszystkie dane wyjściowe zdefiniowane w manifeście automatyzacji. W przeciwnym razie wystąpi błąd.

Ten przykładowy kod zawiera funkcję pomocniczą outputVariables, która tworzy i wysyła podane zmienne jako dane wyjściowe z kroku.

Twój krok jest gotowy do testowania.

Oto kod kroku Kalkulator:

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);
}

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 Apps Script.
    2. Kliknij Wdrożenie > 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 (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 sekcji Automatyzacje. Zanim dodatek się pojawi, może być konieczne odświeżenie sekcji Automatyzacje. Przed użyciem dodatku musisz też przyznać mu autoryzację.

    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. Podczas testowania kroku warto wybrać starter, który można uruchomić samodzielnie, np. wysyłając do siebie e-maila. Jeśli Twój krok wymaga zmiennej wejściowej, skonfiguruj ją jako część danych wyjściowych startera.
    3. Kliknij Dodaj krok. Wybierz utworzony lub zaktualizowany krok o nazwie Oblicz.
    4. Skonfiguruj krok. W przypadku kroku obliczania wybierz 2 wartości i działanie matematyczne. 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 e-mail, możesz dodać krok Wyślij wiadomość w Gmailu. W sekcji Wiadomość kliknij Zmienne i wybierz dane wyjściowe kroku. W przypadku kroku obliczania kliknij Zmienne > Krok 2: Wynik obliczeń > Wynik obliczeń. Zmienna pojawi się jako element w polu Wiadomość.
    6. Kliknij Włącz. Twoja automatyzacja jest gotowa do uruchomienia.

  4. Uruchom automatyzację, uruchamiając jej starter. Jeśli na przykład automatyzacja uruchamia się po otrzymaniu e-maila, wyślij do siebie e-maila.

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