בניית שלב

תצוגה מקדימה מוגבלת: הוספת תוספים ל-Google Workspace Studio נמצאת בתצוגה מקדימה מוגבלת. מידע נוסף

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

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

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

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

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

הגדרת השלב

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

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

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

1. מגדירים את onConfigFunction ואת onExecuteFunction לשמות של הפונקציות המתאימות בקוד של התוסף. בדוגמה הזו, הפונקציות נקראות onConfigCalculate() ו-onExecuteCalculate().
   • ‫onConfigFunction מגדיר את השלב. אם צריך, המערכת אוספת נתונים מהמשתמשים שנדרשים לביצוע השלב, כמו הכתובת לשליחת אימייל. בדוגמה שבמדריך הזה, אנחנו מבקשים שני ערכים ופעולה מתמטית.
   • ‫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": "calculatorDemo",
          "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 מחזירה כרטיס. בכרטיס הזה מוגדר ממשק המשתמש שבו המשתמשים מגדירים את הנתונים של השלב. בדוגמה הזו, 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 input fields are configured to let the user select outputs from previous
 * steps as input values using the `hostAppDataSource` property.
 */
function onConfigCalculate() {
  const firstInput = CardService.newTextInput()
  .setFieldName("value1")
  .setTitle("First Value")
  .setHostAppDataSource(
    CardService.newHostAppDataSource()
      .setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
      )
  );
  const secondInput = CardService.newTextInput()
    .setFieldName("value2")
    .setTitle("Second Value").setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );
  const selectionInput = CardService.newSelectionInput()
    .setTitle("operation")
    .setFieldName("operation")
    .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)

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

  return 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(variableDataMap) {
const workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
  .setVariableDataMap(variableDataMap);

const hostAppAction = AddOnsResponseService.newHostAppAction()
  .setWorkflowAction(workflowAction);

const renderAction = AddOnsResponseService.newRenderActionBuilder()
  .setHostAppAction(hostAppAction)
  .build();

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;
  }

  const variableDataMap = { "result": AddOnsResponseService.newVariableData().addIntegerValue(calculatedValue) };

  return outputVariables(variableDataMap);
}

בדיקת השלב

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

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

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

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

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

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

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

3. יוצרים רצף פעולות שכולל את השלב:

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

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

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

נושאים קשורים

• משתני קלט
• אימות משתנה קלט
• משתני פלט
• הגדרת משאב בהתאמה אישית
• משתנים דינמיים
• רישום פעילות ושגיאות ביומן
• אובייקטים של אירועים ב-Workspace Studio