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

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

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

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

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

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

  • ‫id: מזהה ייחודי של משתנה קלט. כדי לאפשר לסוכן לשייך רכיב קלט של כרטיס הגדרה למשתנה הקלט הזה, השם צריך להיות זהה לשם של רכיב הכרטיס המתאים.
  • ‫description: תיאור של משתנה הקלט שיוצג למשתמשי הקצה.
  • ‫cardinality: מספר הערכים המותרים. הערכים האפשריים הם:
    • ‫SINGLE: מותר להשתמש רק בערך אחד.
  • ‫dataType: סוג הערכים הקבילים. ל-dataType יש את המאפיין basicType שמגדיר את סוג הנתונים. הערכים התקפים כוללים:
    • ‫STRING: מחרוזת אלפאנומרית.
    • ‫INTEGER: מספר.
    • ‫TIMESTAMP: חותמת זמן בפורמט 'אלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch)'. לדוגמה, התאריך 27 בנובמבר 2025 בשעה 16:49:02 UTC מיוצג כ-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"
          }
        }
      ]
    }
  }
}

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

הקוד של השלב כולל פונקציה בשם 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 input fields are configured to let the user select outputs from previous
* workflow steps as input values using the `hostAppDataSource` property.
*/
function onConfigCalculate() {
  const firstInput = CardService.newTextInput()
    .setFieldName("value1") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setTitle("First Value")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );

  const secondInput = CardService.newTextInput()
    .setFieldName("value2") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setTitle("Second Value")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );

  const selectionInput = CardService.newSelectionInput()
    .setTitle("operation")
    .setFieldName("operation") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setType(CardService.SelectionInputType.DROPDOWN)
    .addItem("+", "+", false)
    .addItem("-", "-", true)
    .addItem("x", "x", false)
    .addItem("/", "/", false);

  const sections = CardService.newCardSection()
    .setHeader("Action_sample: Calculate")
    .setId("section_1")
    .addWidget(firstInput)
    .addWidget(selectionInput)
    .addWidget(secondInput)

  let card = CardService.newCardBuilder()
    .addSection(sections)
    .build();

  return card;
}

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

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