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

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

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

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

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

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

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

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

  • ‫id: معرّف فريد لمتغيّر الناتج.
  • ‫description: وصف لمتغيّر الناتج سيتم عرضه للمستخدمين النهائيين.
  • cardinality: عدد القيم المسموح بها القيم المحتمَلة هي:
    • "SINGLE": يُسمح بقيمة واحدة فقط.
  • ‫dataType: نوع القيم المقبولة تحتوي dataType على السمة basicType التي تحدّد نوع البيانات. تشمل القيم الصالحة ما يلي:
    • ‫"STRING": سلسلة أبجدية رقمية
    • ‫"INTEGER": رقم
    • ‫TIMESTAMP: طابع زمني بتنسيق "ملّي ثانية منذ بدء حساب الفترة" على سبيل المثال، يتم تمثيل 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": "actionElement",
          "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();
}