בניית שלב

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

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

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

כרטיס שלב המחשבון ב-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
    },
    "studio": {
      "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 פועל. כל ערכי הקלט שהמשתמש הגדיר במהלך ההגדרה, כפי שמוגדר ב-onConfigFunction, מועברים אל 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. פותחים את Flow.

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

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

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