Tworzenie kroku

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

Krok to pojedynczy etap w sekwencji zadań przepływu. Kroki nie mogą uruchamiać przepływu.

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

Użytkownik konfiguruje krok kalkulatora w ramach procesu.

Ilustracja 1. Użytkownik konfiguruje krok kalkulatora w ramach przepływu.

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. W wersji alfa nie publikuj dodatku, który rozszerza funkcje przepływów.

Definiowanie kroku

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

Zdefiniuj krok 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 mają nazwy onConfigCalculate() i onExecuteCalculate().
    • onConfigFunction konfiguruje krok. W razie potrzeby zbiera dane od użytkowników niezbędne do wykonania kroku, np. adres, na który ma zostać wysłany e-mail. W przykładzie w tym przewodniku prosimy o 2 wartości i działanie matematyczne.
    • onExecuteFunction wykonuje krok. Jeśli dane zostały zebrane od użytkowników, są przekazywane do tej funkcji. W odpowiednich przypadkach zwraca dane wyjściowe. W przykładzie w tym przewodniku zwraca wynik obliczeń matematycznych.

  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 obliczony wynik 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 przepływy działają bez błędów, sprawdź zmienne wejściowe.

Oto plik manifestu dla 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
    },
    "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"
          }
        }
      ]
    }
  }
}

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

Zdefiniuj krok w kodzie

W kodzie aplikacji wykonaj te czynności:

  1. Wpisz onConfigFunction, w tym przykładzie onConfigCalculate(). Gdy użytkownicy dodadzą krok do przepływu, mogą skonfigurować jego aspekty w narzędziu do tworzenia przepływów. Aby zebrać od użytkownika wymagane informacje, element 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 multimedia, np. obrazy. Karty umożliwiają uzyskiwanie od użytkownika danych potrzebnych do wykonania kroku, np. adresu e-mail do wysłania wiadomości.

    Funkcja OnConfigFunction zwraca obiekt RenderActions, który zawiera kartę. Ta karta określa 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. Wpisz onExecuteFunction o nazwie onExecuteCalculate() w tym przykładzie. Gdy krok jest wykonywany w przepływie, uruchamiana jest funkcja OnExecuteFunction. Wszystkie wartości wejściowe ustawione przez użytkownika podczas konfiguracji zgodnie z definicją w onConfigurationFunction są przekazywane do OnExecuteFunction.

    Napisz funkcję OnExecuteFunction(), która synchronicznie wykonuje zadanie przy użyciu podanych danych wejściowych. Pamiętaj, że OnExecuteFunction() musi zwrócić wszystkie dane wyjściowe zdefiniowane w pliku manifestu przepływu, 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.

Krok jest gotowy do testowania.

Oto kod kroku Kalkulator:

Google 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 card also includes a "Save"
 * button to save the step configuration for the workflow.
 *
 * The input fields are configured to let the user select outputs from previous
 * workflow steps as input values using the `hostAppDataSource` property.
 */
function onConfigCalculate() {
  var card = {
    "sections": [
      {
        "header": "Step example: 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 {
    "action": {
      "navigations": [{
        "push_card": 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(variableValues) {
  var renderAction =  {
    "hostAppAction" : {
      "workflowAction" : {
        "returnOutputVariablesAction" : {
          "variables" : variableValues
        }
      }
    }
  };
  console.log("renderAction: " + JSON.stringify(renderAction));
  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;
  }
  return outputVariables([{
    "variableId": "result",
    "variableData": {
        "integerValues": [
          calculatedValue
        ]
      },
  }]);
}

Sprawdź swój krok

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 Wdrażanie > Testuj wdrożenia.
    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 na ich kontach (wymagane są uprawnienia do edycji). Następnie poproś użytkowników o wykonanie poprzednich czynności.

    Po zainstalowaniu dodatek jest od razu dostępny w przepływach. Przed pojawieniem się dodatku może być konieczne odświeżenie Flows. Przed użyciem dodatku musisz go też autoryzować.

    Więcej informacji o wdrażaniu testowym znajdziesz w artykule Instalowanie nieopublikowanego dodatku.

  2. Otwórz przepływy.

  3. Utwórz przepływ zawierający Twój krok:

    1. Kliknij Nowy przepływ.
    2. Wybierz sposób rozpoczęcia przepływu. Podczas testowania kroku warto wybrać starter, który możesz uruchomić samodzielnie, np. wysyłając do siebie e-maila. Jeśli 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 zostanie zapisany automatycznie.
    5. Aby przetestować dane wyjściowe kroku, dodaj kolejny krok. Aby na przykład dodać dane wyjściowe do e-maila, możesz dodać krok Wyślij wiadomość w Gmailu. W sekcji Wiadomość kliknij Zmienne i wybierz dane wyjściowe kroku. W przypadku kroku obliczania wybierz Zmienne > Krok 2. Obliczony wynik > Obliczony wynik. Zmienna pojawi się jako element w polu Wiadomość.
    6. Kliknij Włącz. Przepływ jest gotowy do uruchomienia.

  4. Uruchom przepływ, wywołując jego polecenie inicjujące. Jeśli na przykład Twój przepływ zaczyna się od otrzymania e-maila, wyślij do siebie e-maila.

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