動的変数を定義する

このガイドでは、動的変数を作成する方法について説明します。

可能な場合は、変数をマニフェスト ファイルで 入力変数、出力変数、またはカスタム リソースとして静的に定義する必要があります。ただし、入力の性質が異なるため、ユーザーがエージェントを構成するときにのみ定義できる変数が必要になる場合があります。たとえば、Google フォームの質問と回答の数（およびその内容）は、エージェントの構成時に特定のフォームが選択されるまで特定できません。

動的変数は、マニフェスト ファイルとステップのコードで動的な出力セットを生成する入力を定義することで、これらのケースに対応します。

マニフェスト ファイルで出力変数を定義する

マニフェスト ファイルで、次の手順を行います。

  • inputs[] で、動的な入力値を受け入れる入力変数を指定します。

  • outputs[] で、出力変数の動的セットを返す出力変数を指定します。この出力に "workflowResourceDefinitionId": "dynamic_resource_id" の dataType を指定します。

  • 動的変数を処理するカスタム リソースを定義します。"resourceType": "DYNAMIC" と "providerFunction": "onDynamicProviderFunction" を使用して workflowResourceDefinitions を指定します。id は、outputs[] で設定された workflowResourceDefinitionId と一致する必要があります。カスタム リソースの詳細については、カスタム リソースを定義するをご覧ください。

  • dynamicResourceDefinitionProvider を、ステップのコード内の対応する関数の名前に設定します。この例では、動的入力値を受け入れてカスタム リソースを返す構成カードを定義して返す onDynamicDefinitionFunction() です。

JSON

"flows": {
  "workflowElements" : [{
    "id": "getDynamicVariable",
    "state": "ACTIVE",
    "name": "Get Dynamic Variable",
    "description": "Get Dynamic Variable",
    "workflowAction": {
    "inputs": [
      {
          "id": "dynamic_resource_input",
          "description": "Dynamic Resource Input",
          "cardinality": "SINGLE",
          "dataType": {
            "basicType": "INTEGER"
          }
       }
      ],
      "outputs": [
        {
          "id": "dynamic_resource_output",
          "description": "Dynamic Data",
          "cardinality": "SINGLE",
          "dataType": {
            "resourceType": {
              "workflowResourceDefinitionId": "resource_definition_1"
            }
          }
        }
      ],
      "onConfigFunction": "onDynamicVariableConfigFunction",
      "onExecuteFunction": "onDynamicVariableExecuteFunction"
    }
  }],
  "workflowResourceDefinitions": [{
    "id": "resource_definition_1",
    "name": "Dynamic Resource",
    "providerFunction": "onDynamicProviderFunction",
    "resourceType" : "DYNAMIC"
  }],
  "dynamicResourceDefinitionProvider" : "onDynamicDefinitionFunction",
}

コードで出力変数を定義する

このステップのコードには、次の関数が含まれています。

  • onDynamicVariableConfigFunction()。動的入力ウィジェットを含む構成カードを作成して返します。この関数の名前は、マニフェスト ファイルの onConfigFunction() の値と一致している必要があります。動的入力ウィジェットの名前は、マニフェスト ファイルで設定された id と一致する必要があります。この動的入力ウィジェットを使用すると、ユーザーはステップの構成時に動的変数を設定できます（Google フォームの選択など）。
  • onDynamicVariableExecuteFunction()。ステップの実行時に動的変数データを出力として返します。この関数の名前は、マニフェスト ファイルの onExecuteFunction() の値と一致する必要があります。returnOutputVariablesAction の variableData のキーは、マニフェスト ファイルで設定された出力変数の id と一致する必要があります。動的リソースは、イベント オブジェクトの e.workflow.resourceFieldsDefinitionRetrieval にあります。動的リソースのすべての入力は構成時に使用可能である必要があるため、入力で変数を参照することはできません。
  • onDynamicDefinitionFunction()。イベント オブジェクト（特に resourceFieldsDefinitionRetrieval）から動的変数データを取得し、後続のステップの出力変数の名前を提供する resourceFieldsDefinitionRetrievedAction と、onDynamicProviderFunction() が各出力変数に対応する値を提供できるようにセレクタを返します。resourceId は、マニフェスト ファイルで設定された workflowResourceDefinitions[] 配列内のアイテムの id と一致する必要があります。

  • onDynamicProviderFunction(): resourceId と workflowResourceDefinitionId にアクセスして、セレクタをキーとして使用し、各出力変数の値を提供します。

Apps Script

function onDynamicVariableConfigFunction() {
  let section = CardService.newCardSection()
    .addWidget(
      CardService.newTextInput()
        .setFieldName("dynamic_resource_input")
        .setTitle("Dynamic Resource Input")
        .setHint("Input a Integer value between 1 and 3\(inclusive\) for corresponding number of output variables")
    );

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

  return card;
}

function onDynamicDefinitionFunction(e) {
  console.log("Payload in onDynamicDefinitionFunction: ", JSON.stringify(e));
  var input_value = e.workflow.resourceFieldsDefinitionRetrieval.inputs.dynamic_resource_input.integerValues[0];

  let resourceDefinitions = AddOnsResponseService.newDynamicResourceDefinition()
    .setResourceId("resource_definition_1")
    .addResourceField(
      AddOnsResponseService.newResourceField()
        .setSelector("question_1")
        .setDisplayText("Question 1")
    );

  if (input_value == 2 || input_value == 3) {
    resourceDefinitions = resourceDefinitions
      .addResourceField(
        AddOnsResponseService.newResourceField()
          .setSelector("question_2")
          .setDisplayText("Question 2")
      );
  }
  if (input_value == 3) {
    resourceDefinitions = resourceDefinitions
      .addResourceField(
        AddOnsResponseService.newResourceField()
          .setSelector("question_3")
          .setDisplayText("Question 3")
      );
  }

  let workflowAction = AddOnsResponseService.newResourceFieldsDefinitionRetrievedAction()
    .addDynamicResourceDefinition(resourceDefinitions);

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

  let renderAction = AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();

  return renderAction;
}

function onDynamicVariableExecuteFunction(e) {
  console.log("Payload in onDynamicVariableExecuteFunction: ", JSON.stringify(e));

  let workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
    .setVariableDataMap({
      "dynamic_resource_output": AddOnsResponseService.newVariableData()
        .addResourceReference("my_dynamic_resource_id")
    });

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

  let renderAction = AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();

  return renderAction;
}

function onDynamicProviderFunction(e) {
  console.log("Payload in onDynamicProviderFunction: ", JSON.stringify(e));

  // resourceId == "my_dynamic_resource_id"
  var resourceId = e.workflow.resourceRetrieval.resourceReference.resourceId;
  // workflowResourceDefinitionId == "resource_definition_1"
  var workflowResourceDefinitionId = e.workflow.resourceRetrieval.resourceReference.resourceType.workflowResourceDefinitionId;

  const workflowAction = AddOnsResponseService.newResourceRetrievedAction()
    .setResourceData(
      AddOnsResponseService.newResourceData()
        .addVariableData("question_1", AddOnsResponseService.newVariableData().addStringValue("Answer 1"))
        .addVariableData("question_2", AddOnsResponseService.newVariableData().addStringValue("Answer 2"))
        .addVariableData("question_3", AddOnsResponseService.newVariableData().addStringValue("Answer 3"))
    );

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

  const renderAction = AddOnsResponseService.newRenderActionBuilder()
    .setHostAppAction(hostAppAction)
    .build();

  return renderAction;
}