איסוף נתונים באמצעות משתנה קלט

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

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

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

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

במניפסט, מציינים משתני קלט באמצעות המערך inputs[]. כל פריט במערך inputs[] כולל את המאפיינים הבאים:

  • ‫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"
          }
        }
      ]
    }
  }
}

הגדרת משתנה הקלט בקוד

הקוד של השלב כולל פונקציה בשם onConfigFunction() שמחזירה כרטיס הגדרה שמגדיר ווידג'ט של כרטיס קלט אחד לכל משתנה קלט שמוגדר במערך inputs[] של קובץ המניפסט.

לווידג'טים של שדות ההזנה שמוגדרים בכרטיס ההגדרות יש את הדרישות הבאות:

  • הערך name של כל ווידג'ט קלט צריך להיות זהה לערך id של משתנה הקלט התואם בקובץ המניפסט.
  • הקרדינליות של ווידג'ט הקלט צריכה להיות זהה לקרדינליות של משתנה הקלט cardinality בקובץ המניפסט.
  • טיפוס הנתונים של הווידג'ט של הקלט חייב להיות זהה לטיפוס הנתונים של משתנה הקלט dataType בקובץ המניפסט. אם משתנה הקלט הוא dataType מסוג integer, הוא לא יכול להכיל מחרוזת.

כדי לקבל עזרה ביצירת ממשקי כרטיסים, אפשר לעיין באחת מהאפשרויות הבאות:

בדוגמה הבאה מוחזר כרטיס הגדרות לכל ווידג'ט קלט שהוגדר בקטע הגדרת משתנה הקלט בקובץ המניפסט.

Apps Script

/**
 * Generates and displays a configuration card for the sample calculation step.
 *
 * This function creates a card with input fields for two values and a drop-down
 * for selecting an arithmetic operation. The card also includes a "Save"
 * button to save the step configuration for the workflow.
 *
 * The input fields are configured to let the user select outputs from previous
 * workflow steps as input values using the `hostAppDataSource` property.
 */
function onConfigFunction() {
  var card = {
    "sections": [
      {
        "header": "Step example: Calculate",
        "widgets": [
          {
            "textInput": {
              "name": "value1", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "First value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          },
          {
            "selectionInput": {
              "name": "operation", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "Operation",
              "type": "DROPDOWN",
              "items": [
                {
                  "text": "+",
                  "value": "+",
                },
                {
                  "text": "-",
                  "value": "-",
                },
                {
                  "text": "x",
                  "value": "x",
                },
                {
                  "text": "/",
                  "value": "/",
                }
              ]
            }
          },
          {
            "textInput": {
              "name": "value2", // "name" must match an "id" in the manifest file's inputs[] array.
              "label": "Second value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

אימות משתנה הקלט

מומלץ לוודא שהמשתמש מזין ערך מתאים. מידע נוסף זמין במאמר בנושא אימות משתנה קלט.