定義動態變數

本指南說明如何建立動態變數。

如有可能，變數應在資訊清單檔案中靜態定義為輸入變數、輸出變數或自訂資源。不過，在某些情況下，您需要只能在使用者設定代理程式時定義的變數，因為輸入內容的性質各不相同。舉例來說，在設定服務專員時選取特定表單之前，系統無法判斷 Google 表單的問題和答案數量 (以及內容)。

動態變數可讓您定義輸入內容，在資訊清單檔案和步驟的程式碼中產生動態輸出內容集，藉此處理這些情況。

在資訊清單檔案中定義輸出變數

在資訊清單檔案中，按照下列步驟操作：

  • 在 inputs[] 中，指定接受動態輸入值的輸入變數。

  • 在 outputs[] 中，指定會傳回動態輸出變數集的輸出變數。將此輸出內容的 dataType 設為 "workflowResourceDefinitionId": "dynamic_resource_id"。

  • 定義自訂資源來處理動態變數。請指定 workflowResourceDefinitions，並使用 "resourceType": "DYNAMIC" 和 "providerFunction": "onDynamicProviderFunction"。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;
}