העברת נתונים בין שלבים באמצעות משתנה פלט

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

משתני פלט מוחזרים על ידי שלבים ויכולים להישלח לשלב אחר. לדוגמה, אפשר להעביר כתובת אימייל לשלב אחר שמשתמש בה כדי לציין את הנמען של אימייל.

מגדירים את משתנה הפלט בשני מקומות: בקובץ המניפסט של התוסף ובקוד עם פונקציה שמחזירה את משתנה הפלט.

בדוגמה הבאה מוחזרת תוצאה מתמטית מחושבת משלושה משתני קלט: שני מספרים ופעולה אריתמטית.

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

במניפסט של קובץ Apps Script, מציינים מערך outputs[] ו-onExecuteFunction().

כל פריט במערך outputs[] כולל את המאפיינים הבאים:

  • ‫id: מזהה ייחודי של משתנה פלט.
  • ‫description: תיאור של משתנה הפלט שיוצג למשתמשי הקצה.
  • ‫cardinality: כמה ערכים מותרים. הערכים האפשריים הם:
    • ‫"SINGLE": מותר להשתמש רק בערך אחד.
  • ‫dataType: סוג הערכים הקבילים. ל-dataType יש את המאפיין basicType שמגדיר את סוג הנתונים. הערכים התקינים כוללים:
    • ‫"STRING": מחרוזת אלפאנומרית.
    • ‫"INTEGER": מספר.
    • ‫"TIMESTAMP": חותמת זמן בפורמט ISO 8601. לדוגמה, בפורמט ISO 8601, התאריך 15 במרץ 2025 מיוצג כ-2025-03-15.
    • ‫"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 של משתנה הפלט התואם בקובץ המניפסט.

בדוגמה הבאה מוחזר משתנה פלט שהוא הערך האריתמטי של שני מספרי קלט:

Apps Script

/**
 * 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 onExecuteCalculateFunction(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;
  }
  var renderAction = {
    "hostAppAction" : {
      "workflowAction" : {
        "returnOutputVariablesAction" : {
          "variableValues" : [
            {
              "variableId": "result",
              "integerValues": [
                calculatedValue
              ]
            }
          ]
        }
      }
    }
  };

  console.log("renderAction: " + JSON.stringify(renderAction));

  return renderAction;
}