Построить шаг

В этом руководстве объясняется, как создать шаг, который пользователи могут добавить в поток в Google Workspace Flows.

Шаг — это отдельный этап в последовательности задач потока. Шаги не могут начинать поток.

В качестве примера рассмотрим шаг, выполняющий арифметические действия. Он запрашивает у пользователя два значения и математическую операцию. Затем он выполняет математическую операцию над значениями и выводит результат.

Пользователь настраивает шаг калькулятора как часть потока.

Рисунок 1: Пользователь настраивает шаг калькулятора как часть потока.

Чтобы создать шаг, настройте его в файле манифеста дополнения, пропишите логику приложения в коде дополнения Google Workspace, а затем разверните и протестируйте шаг. Во время альфа-тестирования не публикуйте дополнения, расширяющие Flows.

Определите шаг

Чтобы настроить шаг, определите его в файле манифеста и запишите логику его применения в коде.

Определить шаг в файле манифеста

В файле манифеста appsscript.json :

  1. Задайте onConfigFunction и onExecuteFunction в соответствии с именами соответствующих функций в коде дополнения. В этом примере функции называются onConfigCalculate() и onExecuteCalculate() .
    • onConfigFunction настраивает и конфигурирует шаг. При необходимости собирает данные от пользователей, необходимые для выполнения шага, например, адрес для отправки электронного письма. В примере этого руководства мы запрашиваем два значения и математическую операцию.
    • onExecuteFunction выполняет шаг. Если данные были собраны от пользователей, они передаются этой функции. При необходимости возвращает выходные данные. В примере из этого руководства выводит результат математического вычисления.

  2. Задайте необходимые входные и выходные данные, что позволит этапу собирать данные и передавать их на последующие этапы. В этом примере запросите у пользователя два значения и математическую операцию, заданную в inputs[] . Выведите вычисленный результат, как определено в outputs[] .

    Подробнее о входных и выходных данных см. в разделах Входные переменные и Выходные переменные . Чтобы убедиться в отсутствии ошибок, проверьте входные переменные .

Вот файл манифеста для шага Калькулятора:

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

Затем напишите вспомогательный код, определив шаг в коде.

Определить шаг в коде

В коде приложения выполните следующие действия:

  1. Напишите функцию onConfigFunction , которая в этом примере называется onConfigCalculate() . Когда пользователи добавляют шаг в поток, они могут настроить его параметры в конструкторе потока. Для сбора необходимой информации от пользователя функция onConfigFunction определяет карточку конфигурации.

    Карточки — это строительные блоки для пользовательских интерфейсов в дополнениях. Карточки поддерживают заданный макет, интерактивные элементы пользовательского интерфейса, такие как кнопки, и мультимедийные материалы, такие как изображения. Карточки позволяют получать от пользователя данные, необходимые для выполнения шага, например, адрес электронной почты для отправки электронного письма.

    Функция OnConfigFunction возвращает объект RenderActions , содержащий карточку. Эта карточка определяет пользовательский интерфейс, в котором пользователи задают данные шага. В этом примере функция onConfigFunction создаёт карточку, которая запрашивает у пользователя два значения и математическую операцию.

  2. В этом примере напишите функцию onExecuteFunction с именем onExecuteCalculate() . Функция OnExecuteFunction запускается при выполнении шага в потоке. Все входные значения, заданные пользователем во время настройки, как определено в onConfigurationFunction передаются в OnExecuteFunction .

    Напишите OnExecuteFunction() так, чтобы он синхронно выполнял свою задачу, используя предоставленные входные данные. Помните, OnExecuteFunction() должен возвращать все выходные данные, определённые в манифесте вашего потока, иначе возникнет ошибка.

Этот пример кода включает вспомогательную функцию outputVariables() , которая создает и отправляет предоставленные переменные в качестве выходных данных из шага.

Ваш шаг готов к тестированию.

Вот код для шага «Калькулятор»:

Скрипт приложений 

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

Проверьте свой шаг

Чтобы протестировать свой шаг, настройте тестовое развертывание для своего дополнения, добавьте шаг в поток, а затем запустите поток.

  1. Настройте тестовое развертывание для вашего дополнения:

    1. Откройте проект скрипта в редакторе Apps Script.
    2. Нажмите Развернуть > Тестовые развертывания .
    3. Нажмите «Установить» .
    4. Внизу нажмите Готово .

    Вы можете разрешить другим пользователям протестировать дополнение, поделившись проектом Apps Script с их учётной записью (требуется доступ для редактирования). Затем предложите пользователям выполнить предыдущие шаги.

    После установки дополнение сразу же станет доступно в Flows. Возможно, вам потребуется обновить Flows, чтобы оно появилось. Перед использованием необходимо авторизовать дополнение.

    Дополнительную информацию о тестовых развертываниях см. в разделе Установка неопубликованного дополнения .

  2. Открытые потоки.

  3. Создайте поток, включающий ваш шаг:

    1. Нажмите новый поток ».
    2. Выберите способ запуска потока. При тестировании шага рекомендуется выбрать стартовое событие, которое вы можете запустить самостоятельно, например, отправку себе электронного письма. Если для вашего шага требуется входная переменная, настройте её как часть выходных данных стартового события.
    3. Нажмите шаг» . Выберите созданный или обновлённый шаг под названием «Вычислить» .
    4. Настройте шаг. Для шага вычисления выберите два значения и математическую операцию. Шаг сохраняется автоматически.
    5. Чтобы протестировать выходные данные вашего шага, добавьте ещё один шаг. Например, чтобы добавить выходные данные в сообщение электронной почты, можно добавить шаг Gmail «Отправить сообщение» . В разделе «Сообщение » нажмите переменные» и выберите выходные данные вашего шага. Для шага вычисления выберите переменные» > «Шаг 2: Вычисленный результат» > «Вычисленный результат» . Переменная отображается в виде фишки в поле «Сообщение» .
    6. Нажмите «Включить» . Ваш поток готов к запуску.

  4. Запустите поток, активировав его стартовое состояние. Например, если поток запускается при получении электронного письма, отправьте себе письмо.

  5. Убедитесь, что поток выполняется должным образом. Проверьте журналы, перейдя на вкладку «Активность» конструктора потоков. Чтобы узнать, как создавать пользовательские журналы на вкладке «Активность», см. раздел Журналы активности .