בניית שלב

במדריך הזה מוסבר איך ליצור שלב שמשתמשים יכולים להוסיף לתהליך עבודה ב-Google Workspace Flows.

שלב הוא שלב יחיד ברצף המשימות של זרימת עבודה. אי אפשר להתחיל זרימה באמצעות שלבים.

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

משתמש מגדיר את שלב המחשבון כחלק מתהליך.

איור 1: משתמש מגדיר את שלב המחשבון כחלק מתהליך.

כדי ליצור שלב, צריך להגדיר אותו בקובץ המניפסט של התוסף, לכתוב את הלוגיקה של האפליקציה בקוד של התוסף ל-Google Workspace, ולפרוס ולבדוק את השלב. במהלך שלב האלפא, אל תפרסמו תוסף שמרחיב את Flows.

הגדרת השלב

כדי להגדיר שלב, מגדירים אותו בקובץ המניפסט וכותבים את הלוגיקה של האפליקציה בקוד.

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

בקובץ המניפסט, appsscript.json:

  1. מגדירים את onConfigFunction ואת onExecuteFunction לשמות של הפונקציות המתאימות בקוד של התוסף. בדוגמה הזו, הפונקציות נקראות onConfigCalculate() ו-onExecuteCalculate().
    • הקוד onConfigFunction מגדיר את השלב. אם צריך, מערכת Gemini אוספת נתונים מהמשתמשים שנדרשים לביצוע השלב, כמו הכתובת לשליחת אימייל. בדוגמה שבמדריך הזה, אנחנו מבקשים שני ערכים ופעולה מתמטית.
    • ‫onExecuteFunction מבצע את השלב. אם נאספו נתונים מהמשתמשים, הנתונים האלה מועברים לפונקציה הזו. אם רלוונטי, הפונקציה מחזירה פלט. בדוגמה של המדריך הזה, הפלט הוא התוצאה של חישוב מתמטי.

  2. מגדירים את קלט ופלט נדרשים, כדי שהשלב יוכל לאסוף נתונים ולשלוח אותם לשלבים הבאים. בדוגמה הזו, מבקשים מהמשתמש שני ערכים ופעולה מתמטית שמוגדרת ב-inputs[]. הפלט של התוצאה המחושבת צריך להיות בהתאם למוגדר ב-outputs[].

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

זהו קובץ המניפסט של שלב המחשבון:

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

לאחר מכן, כותבים את קוד התמיכה על ידי הגדרת השלב בקוד.

הגדרת השלב בקוד

בתוך קוד האפליקציה, מבצעים את הפעולות הבאות:

  1. כותבים את onConfigFunction, שנקרא onConfigCalculate() בדוגמה הזו. כשמשתמשים מוסיפים את השלב לזרימה, הם יכולים להגדיר את ההיבטים של השלב בכלי ליצירת זרימות. כדי לאסוף את הפרטים הנדרשים מהמשתמש, onConfigFunction מגדיר כרטיס הגדרה.

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

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

  2. כותבים את onExecuteFunction שנקרא onExecuteCalculate() בדוגמה הזו. כשהשלב פועל בתהליך, הפעולה OnExecuteFunction מתבצעת. כל ערכי הקלט שהמשתמש הגדיר במהלך ההגדרה, כפי שמוגדר ב-onConfigurationFunction, מועברים אל OnExecuteFunction.

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

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

השלב מוכן לבדיקה.

הנה הקוד של שלב המחשבון:

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 onConfigCalculate() {
  var card = {
    "sections": [
      {
        "header": "Step example: Calculate",
        "widgets": [
          {
            "textInput": {
              "name": "value1",
              "label": "First value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          },
          {
            "selectionInput": {
              "name": "operation",
              "label": "Operation",
              "type": "DROPDOWN",
              "items": [
                {
                  "text": "+",
                  "value": "+",
                },
                {
                  "text": "-",
                  "value": "-",
                },
                {
                  "text": "x",
                  "value": "x",
                },
                {
                  "text": "/",
                  "value": "/",
                }
              ]
            }
          },
          {
            "textInput": {
              "name": "value2",
              "label": "Second value",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

/**
 * Returns output variables from a step.
 *
 * This function constructs an object that, when returned, sends the
 * provided variable values as output from the current step.
 * The variable values are logged to the console for debugging purposes.
 */
function outputVariables(variableValues) {
  var renderAction =  {
    "hostAppAction" : {
      "workflowAction" : {
        "returnOutputVariablesAction" : {
          "variables" : variableValues
        }
      }
    }
  };
  console.log("renderAction: " + JSON.stringify(renderAction));
  return renderAction;
}

/**
 * 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"].integerValues[0];
  var value2 = event.workflow.actionInvocation.inputs["value2"].integerValues[0];
  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;
  }
  return outputVariables([{
    "variableId": "result",
    "variableData": {
        "integerValues": [
          calculatedValue
        ]
      },
  }]);
}

בדיקת השלב

כדי לבדוק את השלב, מגדירים פריסת בדיקה לתוסף, מוסיפים את השלב לזרימת עבודה ומריצים את זרימת העבודה.

  1. מגדירים פריסת בדיקה לתוסף:

    1. פותחים את פרויקט הסקריפט בכלי לעריכת סקריפטים של Apps Script.
    2. לוחצים על פריסה > בדיקת פריסות.
    3. לוחצים על התקנה.
    4. למטה, לוחצים על סיום.

    אתם יכולים לשתף את פרויקט Apps Script עם חשבון של משתמש אחר (נדרשת גישת עריכה) כדי לאפשר לו לבדוק את התוסף. לאחר מכן, מבקשים מהמשתמשים לפעול לפי השלבים הקודמים.

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

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

  2. פותחים את Flows.

  3. יוצרים תהליך שכולל את השלב:

    1. לוחצים על New flow (יצירת תהליך חדש).
    2. בוחרים איך התהליך יתחיל. כשבודקים שלב, מומלץ לבחור התחלה שאפשר להפעיל לבד, כמו שליחת אימייל לעצמכם. אם השלב דורש משתנה קלט, צריך להגדיר את משתנה הקלט כחלק מהפלט של ה-starter.
    3. לוחצים על הוספת שלב. בוחרים את השלב שיצרתם או עדכנתם, שנקרא Calculate (חישוב).
    4. מגדירים את השלב. בשלב החישוב, בוחרים שני ערכים ופעולה מתמטית. השלב נשמר באופן אוטומטי.
    5. כדי לבדוק את הפלט של השלב, מוסיפים עוד שלב. לדוגמה, כדי להוסיף פלט להודעת אימייל, אפשר להוסיף את השלב שליחת הודעה של Gmail. בקטע הודעה, לוחצים על משתנים ובוחרים את הפלט של השלב. בשלב החישוב, בוחרים באפשרות משתנים > שלב 2: תוצאה מחושבת > תוצאה מחושבת. המשתנה מופיע כצ'יפ בשדה הודעה.
    6. לוחצים על הפעלה. התהליך מוכן להפעלה.

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

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