Представление сложных данных с помощью пользовательского ресурса

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

Пользовательские ресурсы — это пользовательские структуры данных, которые можно определить для группировки нескольких переменных. Если выходные данные шага имеют статическую структуру, представьте их с помощью пользовательского ресурса. Например, для создания лида CRM-системы выходные данные должны содержать несколько переменных:

  • Адрес электронной почты
  • адрес улицы
  • Имя

Чтобы обеспечить наличие всех данных, необходимых для создания лида CRM, выведите пользовательский ресурс, содержащий адрес электронной почты, почтовый адрес и имя.

Вывести пользовательский ресурс в качестве ссылки

Выводя пользовательский ресурс в качестве ссылки, вы можете вернуть пользовательский ресурс по его идентификатору, а не по полному объекту. Если пользовательский ресурс большой или сложный, передача только идентификатора повышает производительность за счёт сокращения объёма данных, передаваемых между этапами.

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

Редактировать файл манифеста

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

  1. Укажите workflowResourceDefinitions и назначьте ему id , массив fields[] и функцию providerFunction . workflowResourceDefinitions — это структура, которая определяет типы данных и содержимое пользовательского ресурса.

  2. В массиве fields[] вы указываете отдельные поля, составляющие пользовательский ресурс, в этом примере называемые field_1 и field_2 .

  3. Значение providerFunction должно соответствовать имени функции в коде шага. Функция providerFunction извлекает фактическое содержимое пользовательского ресурса при необходимости.

    JSON 

    {
  "workflowResourceDefinitions": [
    {
      "id": "resource_id",
      "name": "Custom Resource",
      "fields": [
        {
          "selector": "field_1",
          "name": "Field 1",
          "dataType": {
            "basicType": "STRING"
          }
        },
        {
          "selector": "field_2",
          "name": "Field 2",
          "dataType": {
            "basicType": "STRING"
          }
        }
      ],
      "providerFunction": "onMessageResourceFunction"
    }
  ]
}

  4. В outputs[] укажите выходную переменную, которая возвращает динамический набор выходных переменных. Выходная переменная имеет dataType со свойством resourceType . Значение параметра cardinality должно быть SINGLE .

    JSON 

    {
  "outputs": [
    {
      "id": "resource_data",
      "description": "Resource Data",
      "cardinality": "SINGLE",
      "dataType": {
        "resourceType": {
          "workflowResourceDefinitionId": "resource_id"
        }
      }
    }
  ],
}

Вот полный файл манифеста, определяющий пользовательский ресурс:

JSON 

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Custom Resource (as reference)",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "getResourceDataReference",
          "state": "ACTIVE",
          "name": "Custom Resource (as reference)",
          "description": "Output a custom resource as a reference",
          "workflowAction": {
            "outputs": [
              {
                "id": "resource_data",
                "description": "Resource Data",
                "cardinality": "SINGLE",
                "dataType": {
                  "resourceType": {
                    "workflowResourceDefinitionId": "resource_id"
                  }
                }
              }
            ],
            "onConfigFunction": "onConfigResourceFunction",
            "onExecuteFunction": "onExecuteResourceFunction"
          }
        }
      ],
      "workflowResourceDefinitions": [
        {
          "id": "resource_id",
          "name": "Custom Resource",
          "fields": [
            {
              "selector": "field_1",
              "name": "Field 1",
              "dataType": {
                "basicType": "STRING"
              }
            },
            {
              "selector": "field_2",
              "name": "Field 2",
              "dataType": {
                "basicType": "STRING"
              }
            }
          ],
          "providerFunction": "onMessageResourceFunction"
        }
      ]
    }
  }
}

Изменить код

В коде приложения:

  1. Реализуйте функцию providerFunction , которая в этом примере называется onMessageResourceFunction() и которая при необходимости извлекает содержимое пользовательского ресурса. Она принимает входные данные e , представляющие собой полезную нагрузку JSON-объекта события шага, и устанавливает на их основе идентификатор пользовательского ресурса.

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

    function onMessageResourceFunction(e) {
  console.log("Payload in onMessageResourceFunction: " + JSON.stringify(e));

  var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
  let fieldValue_1;
  let fieldValue_2;

  // Using a if-condition to mock a database call.
  if (resource_id == "sample_resource_reference_id") {
    fieldValue_1 = AddOnsResponseService.newVariableData()
      .addStringValue("value1");
    fieldValue_2 = AddOnsResponseService.newVariableData()
      .addStringValue("value2");
  } else {
    fieldValue_1 = AddOnsResponseService.newVariableData()
      .addStringValue("field_1 value not found");
    fieldValue_2 = AddOnsResponseService.newVariableData()
      .addStringValue("field_2 value not found");
  }

  let resourceData = AddOnsResponseService.newResourceData()
    .addVariableData("field_1", fieldValue_1)
    .addVariableData("field_2", fieldValue_2)

  let workflowAction = AddOnsResponseService.newResourceRetrievedAction()
    .setResourceData(resourceData)

  let hostAppAction = AddOnsResponseService.newHostAppAction()
    .setWorkflowAction(workflowAction);

  return AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();
}

  2. Функция поставщика должна возвращать значение пользовательского ресурса, извлекая его с помощью соответствующего механизма, например, вызывая API или читая базу данных.

  3. Чтобы извлечь и вернуть пользовательский ресурс по его идентификатору, верните его как returnOutputVariablesAction , как показано в onExecuteResourceFunction() .

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

    function onExecuteResourceFunction(e) {
  console.log("Payload in onExecuteResourceFunction: " + JSON.stringify(e));

  let outputVariables = AddOnsResponseService.newVariableData()
    .addResourceReference("sample_resource_reference_id");

  let workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
    .addVariableData("resource_data", outputVariables);

  let hostAppAction = AddOnsResponseService.newHostAppAction()
    .setWorkflowAction(workflowAction);

  return AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();
}

Вот полный пример:

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

function onConfigResourceFunction() {
  let section = CardService.newCardSection()
    .addWidget(
      CardService.newTextParagraph()
        .setText("This is the Custom Resource Demo card")
    );

  const card = CardService.newCardBuilder()
    .addSection(section)
    .build();

  return card;
}

function onMessageResourceFunction(e) {
  console.log("Payload in onMessageResourceFunction: " + JSON.stringify(e));

  var resource_id = e.workflow.resourceRetrieval.resourceReference.resourceId;
  let fieldValue_1;
  let fieldValue_2;

  // Using a if-condition to mock a database call.
  if (resource_id == "sample_resource_reference_id") {
    fieldValue_1 = AddOnsResponseService.newVariableData()
      .addStringValue("value1");
    fieldValue_2 = AddOnsResponseService.newVariableData()
      .addStringValue("value2");
  } else {
    fieldValue_1 = AddOnsResponseService.newVariableData()
      .addStringValue("field_1 value not found");
    fieldValue_2 = AddOnsResponseService.newVariableData()
      .addStringValue("field_2 value not found");
  }

  let resourceData = AddOnsResponseService.newResourceData()
    .addVariableData("field_1", fieldValue_1)
    .addVariableData("field_2", fieldValue_2)

  let workflowAction = AddOnsResponseService.newResourceRetrievedAction()
    .setResourceData(resourceData)

  let hostAppAction = AddOnsResponseService.newHostAppAction()
    .setWorkflowAction(workflowAction);

  return AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();
}

function onExecuteResourceFunction(e) {
  console.log("Payload in onExecuteResourceFunction: " + JSON.stringify(e));

  let outputVariables = AddOnsResponseService.newVariableData()
    .addResourceReference("sample_resource_reference_id");

  let workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
    .addVariableData("resource_data", outputVariables);

  let hostAppAction = AddOnsResponseService.newHostAppAction()
    .setWorkflowAction(workflowAction);

  return AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();
}