הגדרת משתנה דינמי

במאמר הזה מוסבר איך ליצור משתנה דינמי.

אם אפשר, צריך להגדיר משתנה באופן סטטי בקובץ המניפסט כמשתנה קלט, כמשתנה פלט או כמשאב מותאם אישית. עם זאת, יש מצבים שבהם נדרש משתנה שאפשר להגדיר רק כשהמשתמש מגדיר את הסוכן, כי אופי הקלט משתנה. לדוגמה, אי אפשר לקבוע את מספר השאלות והתשובות (והתוכן שלהן) ב-Google Forms עד שבוחרים טופס ספציפי במהלך הגדרת הסוכן.

משתנים דינמיים מאפשרים לכם להגדיר קלט שמפיק קבוצה דינמית של פלטים בקובץ המניפסט ובקוד של השלב, וכך לטפל במקרים האלה.

הגדרת משתנה הפלט בקובץ המניפסט

בקובץ המניפסט, פועלים לפי השלבים הבאים:

  • ב-inputs[], מציינים משתנה קלט שמקבל ערך קלט דינמי.

  • ב-outputs[], מציינים משתנה פלט שמחזיר קבוצה דינמית של משתני פלט. הפלט הזה הוא dataType של "workflowResourceDefinitionId": "dynamic_resource_id".

  • מגדירים משאב מותאם אישית לטיפול במשתנה הדינמי. צריך לציין את workflowResourceDefinitions עם "resourceType": "DYNAMIC" וגם "providerFunction": "onDynamicProviderFunction". הערך של id צריך להיות זהה לערך של workflowResourceDefinitionId שמוגדר ב-outputs[]. מידע נוסף על משאבים מותאמים אישית זמין במאמר הגדרת משאב מותאם אישית.

  • מגדירים את 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() בקובץ המניפסט. המפתח של variableData ב-returnOutputVariablesAction צריך להיות זהה לערך של משתנה הפלט id שמוגדר בקובץ המניפסט. המשאב הדינמי נמצא באובייקט האירוע בכתובת e.workflow.resourceFieldsDefinitionRetrieval. הקלט לא יכול להפנות למשתנים כי כל הקלטים של משאב דינמי צריכים להיות זמינים בזמן ההגדרה.
  • ‫onDynamicDefinitionFunction(), שמחלץ את נתוני המשתנים הדינמיים מאובייקט האירוע, במיוחד resourceFieldsDefinitionRetrieval, ומחזיר את resourceFieldsDefinitionRetrievedAction.‫resourceFieldsDefinitionRetrievedAction מספק את השם של משתני הפלט לשלבים הבאים, וגם את הסלקטורים כדי ש-onDynamicProviderFunction() יוכל לספק את הערך המתאים לכל משתנה פלט. הערך של resourceId צריך להיות זהה לערך של id של פריט במערך workflowResourceDefinitions[] שמוגדר בקובץ המניפסט.

  • ‫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;
}