تحديد متغيّر ديناميكي

يوضّح هذا الدليل كيفية إنشاء متغيّر ديناميكي.

يجب تحديد قيمة ثابتة للمتغير في ملف البيان كـ متغير إدخال أو متغير إخراج أو مورد مخصّص، متى أمكن ذلك. ومع ذلك، تتطلّب بعض الحالات متغيّرًا لا يمكن تحديده إلا عندما يضبط المستخدم إعدادات البرنامج لأنّ طبيعة الإدخال تختلف. على سبيل المثال، لا يمكن تحديد عدد الأسئلة والأجوبة (ومحتواها) في "نماذج Google" إلا بعد اختيار نموذج معيّن أثناء إعداد الوكيل.

تراعي المتغيّرات الديناميكية هذه الحالات من خلال السماح لك بتحديد إدخال ينتج مجموعة ديناميكية من المخرجات في ملف البيان وفي رمز الخطوة.

تحديد متغيّر الإخراج في ملف البيان

في ملف البيان، اتّبِع الخطوات التالية:

  • في 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 التي توفّر أسماء متغيّرات الإخراج للخطوات اللاحقة، بالإضافة إلى أدوات الاختيار حتى يتمكّن onDynamicProviderFunction() من توفير القيمة المقابلة لكل متغيّر إخراج. يجب أن يتطابق resourceId مع id الخاص بعنصر في مصفوفة workflowResourceDefinitions[] المحدّدة في ملف البيان.

  • ‫onDynamicProviderFunction(): تقدّم هذه السمة قيمة لكل متغيّر إخراج باستخدام أدوات الاختيار كمفاتيح من خلال الوصول إلى resourceId وworkflowResourceDefinitionId.

برمجة التطبيقات

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