نقل البيانات بين الخطوات باستخدام متغيّر إخراج

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

تعرض الخطوات متغيّرات الناتج ويمكن إرسالها إلى خطوة أخرى. على سبيل المثال، يمكنك تمرير عنوان بريد إلكتروني إلى خطوة أخرى تستخدمه لتحديد المستلِم لرسالة إلكترونية.

يمكنك تحديد متغيّر الناتج في مكانَين: ملف بيان الإضافة وفي الرمز البرمجي باستخدام دالة تعرض متغيّر الناتج.

يعرض المثال التالي نتيجة رياضية محسوبة من ثلاثة متغيّرات إدخال: عددان وعملية حسابية.

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

في ملف بيان "برمجة التطبيقات"، حدِّد مصفوفة outputs[] وonExecuteFunction.

يحتوي كل عنصر في مصفوفة outputs[] على الخصائص التالية:

  • id: معرّف فريد لمتغيّر الناتج.
  • description: وصف لمتغيّر الناتج يتم عرضه للمستخدِمين النهائيين.
  • cardinality: عدد القيم المسموح بها. القيم المحتمَلة هي:
    • SINGLE: يُسمح بقيمة واحدة فقط.
  • dataType: نوع القيم المقبولة. تحتوي dataType على السمة basicType التي تحدّد نوع البيانات. تشمل القيم الصالحة ما يلي:
    • STRING: سلسلة أبجدية رقمية.
    • INTEGER: رقم.
    • TIMESTAMP: طابع زمني بتنسيق "عدد الملّي ثواني منذ حقبة Unix". على سبيل المثال، يتم تمثيل 27 نوفمبر 2025، الساعة 16:49:02 بالتوقيت العالمي المنسَّق على النحو التالي: 1764262142988.
    • BOOLEAN: إما true أو false.
    • EMAIL_ADDRESS: عنوان بريد إلكتروني بالتنسيق dana@example.com.

يحدّد المثال التالي متغيّر ناتج لخطوة آلة حاسبة. متغيّر الناتج هو عدد صحيح.

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Calculator",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/calculator_search/v1/web-24dp/logo_calculator_search_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "calculatorDemo",
          "state": "ACTIVE",
          "name": "Calculate",
          "description": "Asks the user for two values and a math operation, then performs the math operation on the values and outputs the result.",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "value1",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "value2",
                "description": "value2",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "operation",
                "description": "operation",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "outputs": [
              {
                "id": "result",
                "description": "Calculated result",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              }
            ],
            "onConfigFunction": "onConfigCalculate",
            "onExecuteFunction": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

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

يتضمّن الرمز البرمجي للخطوة دالة تُسمى onExecuteCalculate، وهي onExecuteFunction المحدّدة في البيان. تُجري هذه الدالة عملية حسابية على قيمتَين يُدخلهما المستخدِم، وتعرض النتيجة كمتغيّر ناتج باستخدام دالة تُسمى outputVariables.

لعرض متغيّر ناتج، يجب عرض JSON يستوفي المتطلبات التالية:

  • يجب أن يتطابق variableId لكل متغيّر ناتج مع id متغيّر الناتج المقابل في ملف البيان.
  • يجب أن يتطابق variableData لمتغيّر الناتج مع dataType وcardinality لمتغيّر الناتج المقابل في ملف البيان.

يعرض المثال التالي متغيّر ناتج يمثّل القيمة الحسابية لعددَين من أرقام الإدخال:

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

/**
 * Executes the calculation step based on the inputs from a flow event.
 *
 * This function retrieves input values and the operation from the flow event,
 * performs the calculation, and returns the result as an output variable.
 * The function logs the event for debugging purposes.
 */
function onExecuteCalculate(event) {
  console.log("output: " + JSON.stringify(event));
  var calculatedValue = 0;
  var value1 = event.workflow.actionInvocation.inputs["value1"];
  var value2 = event.workflow.actionInvocation.inputs["value2"];
  var operation = event.workflow.actionInvocation.inputs["operation"].stringValues[0];

  if (operation == "+") {
    calculatedValue = value1 + value2;
  } else if (operation == "-") {
    calculatedValue = value1 - value2;
  } else if (operation == "x") {
    calculatedValue = value1 * value2;
  } else if (operation == "/") {
    calculatedValue = value1 / value2;
  }
  const variableData = AddOnsResponseService.newVariableData()
    .addIntegerValue(calculatedValue);
  
  const workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
    .addVariableData("result", variableData);

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

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