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

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

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

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

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

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

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

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

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

В файле манифеста 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 возвращает карточку. Эта карточка определяет пользовательский интерфейс, в котором пользователи задают данные шага. В этом примере функция 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 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);
}

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

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

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

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

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

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

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

2. Открытые агенты.

3. Создайте агента, который включает ваш шаг:

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

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

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

Похожие темы

• Входные переменные
• Проверить входную переменную
• Выходные переменные
• Определить пользовательский ресурс
• Динамические переменные
• Журнал активности и ошибок
• Объекты событий Workspace Studio