ساخت یک پله

برنامه آلفای جمینی: فلوز به عنوان بخشی از برنامه آلفای جمینی در دسترس است.

این راهنما نحوه ایجاد مرحله‌ای را که کاربران می‌توانند به یک جریان در Google Workspace Flows اضافه کنند، توضیح می‌دهد.

یک گام، یک مرحله واحد در توالی وظایف یک جریان است. گام‌ها نمی‌توانند یک جریان را شروع کنند.

به عنوان مثال، مرحله‌ای را در نظر بگیرید که محاسبات را انجام می‌دهد. از کاربر دو مقدار و یک عملیات ریاضی می‌پرسد. سپس عملیات ریاضی را روی مقادیر انجام می‌دهد و نتیجه را نمایش می‌دهد.

شکل ۱: کاربر مرحله محاسبه‌گر را به عنوان بخشی از یک جریان پیکربندی می‌کند.

برای ساخت یک مرحله، آن را در فایل مانیفست افزونه پیکربندی کنید، منطق برنامه را در کد افزونه Google Workspace بنویسید و مرحله را مستقر و آزمایش کنید. در طول نسخه آلفا، افزونه‌ای را که Flows را گسترش می‌دهد منتشر نکنید.

مرحله را تعریف کنید

برای پیکربندی یک مرحله، آن را در فایل مانیفست تعریف کنید و منطق کاربرد آن را به صورت کد بنویسید.

مرحله را در فایل مانیفست تعریف کنید

در فایل مانیفست، appsscript.json :

1. onConfigFunction و onExecuteFunction به نام توابع مربوطه در کد افزونه تنظیم کنید. در این مثال، توابع onConfigCalculate() و onExecuteCalculate() نامیده می‌شوند.
   • onConfigFunction مرحله را تنظیم و پیکربندی می‌کند. در صورت لزوم، داده‌های لازم برای اجرای مرحله، مانند آدرس ارسال ایمیل، را از کاربران جمع‌آوری می‌کند. در مثال این راهنما، ما دو مقدار و یک عملیات ریاضی را درخواست می‌کنیم.
   • onExecuteFunction مرحله را اجرا می‌کند. اگر داده‌ها از کاربران جمع‌آوری شده باشند، آن داده‌ها به این تابع منتقل می‌شوند. در صورت لزوم، یک خروجی برمی‌گرداند. در مثال این راهنما، نتیجه یک محاسبه ریاضی را خروجی می‌دهد.

2. ورودی‌ها و خروجی‌های مورد نیاز را تنظیم کنید، که به مرحله اجازه می‌دهد داده‌ها را جمع‌آوری کرده و به مراحل بعدی ارسال کند. در این مثال، از کاربر دو مقدار و یک عملیات ریاضی تعریف شده در inputs[] را بپرسید. نتیجه محاسبه شده را همانطور که در outputs[] تعریف شده است، در خروجی نمایش دهید.

   برای کسب اطلاعات بیشتر در مورد ورودی‌ها و خروجی‌ها، به متغیرهای ورودی و متغیرهای خروجی مراجعه کنید. برای اطمینان از اجرای بدون خطا، متغیرهای ورودی را اعتبارسنجی کنید .

فایل مانیفست مربوط به مرحله Calculator به صورت زیر است:

جی‌سون

{
  "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 را برمی‌گرداند که شامل یک کارت است. این کارت، رابط کاربری (UI) را تعریف می‌کند که کاربران داده‌های مرحله را در آن تنظیم می‌کنند. در این مثال، تابع onConfigFunction یک کارت می‌سازد که از کاربر دو مقدار و یک عملیات ریاضی را درخواست می‌کند.

2. تابع onExecuteFunction به نام onExecuteCalculate() را در این مثال بنویسید. وقتی مرحله شما در یک جریان اجرا می‌شود، OnExecuteFunction اجرا می‌شود. هر مقدار ورودی که کاربر در طول پیکربندی، همانطور که در onConfigurationFunction تعریف شده است، تنظیم کرده باشد، به OnExecuteFunction ارسال می‌شود.

   OnExecuteFunction() را طوری بنویسید که به صورت همزمان وظیفه خود را با استفاده از ورودی‌های ارائه شده اجرا کند. به یاد داشته باشید، OnExecuteFunction() باید تمام خروجی‌های تعریف شده در مانیفست جریان شما را برگرداند، در غیر این صورت خطایی رخ می‌دهد.

این نمونه کد شامل یک تابع پشتیبانی outputVariables() است که متغیرهای ارائه شده را به عنوان خروجی از مرحله می‌سازد و ارسال می‌کند.

مرحله شما آماده آزمایش است.

کد مربوط به مرحله Calculator به صورت زیر است:

اسکریپت برنامه‌ها

/**
 * 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. جریان‌های باز.

3. جریانی ایجاد کنید که شامل مراحل شما باشد:

   1. روی جریان جدید کلیک کنید.
   2. نحوه شروع جریان را انتخاب کنید. هنگام آزمایش یک مرحله، ایده خوبی است که یک شروع‌کننده را انتخاب کنید که بتوانید خودتان آن را تنظیم کنید، مانند ارسال یک ایمیل به خودتان. اگر مرحله شما به یک متغیر ورودی نیاز دارد، متغیر ورودی را به عنوان بخشی از خروجی شروع‌کننده پیکربندی کنید.
   3. روی مرحله کلیک کنید. مرحله‌ای را که ساخته یا به‌روزرسانی کرده‌اید، با نام محاسبه ، انتخاب کنید.
   4. مرحله خود را پیکربندی کنید. برای مرحله محاسبه، دو مقدار و یک عملیات ریاضی انتخاب کنید. مرحله به طور خودکار ذخیره می‌شود.
   5. برای آزمایش خروجی مرحله خود، یک مرحله دیگر اضافه کنید. برای مثال، برای افزودن خروجی به یک پیام ایمیل، می‌توانید مرحله ارسال پیام Gmail را اضافه کنید. در پیام ، روی متغیرها کلیک کنید و خروجی مرحله خود را انتخاب کنید. برای مرحله محاسبه، گزینه متغیرها > مرحله 2: نتیجه محاسبه شده > نتیجه محاسبه شده را انتخاب کنید. متغیر به صورت یک تراشه در فیلد پیام ظاهر می‌شود.
   6. روی روشن کردن کلیک کنید. جریان شما آماده اجرا است.

4. با شروع جریان خود، جریان را به جریان بیندازید. برای مثال، اگر جریان شما با دریافت ایمیل شروع می‌شود، برای خودتان یک ایمیل بفرستید.

5. تأیید کنید که جریان مطابق انتظار اجرا می‌شود. با مراجعه به برگه فعالیت سازنده جریان، گزارش‌ها را بررسی کنید. برای یادگیری نحوه ایجاد گزارش‌های سفارشی در برگه فعالیت، به گزارش‌های فعالیت مراجعه کنید.

مباحث مرتبط

• متغیرهای ورودی
• اعتبارسنجی یک متغیر ورودی
• متغیرهای خروجی
• تعریف منبع سفارشی
• متغیرهای پویا
• ثبت فعالیت‌ها و خطاها
• شیء رویداد جریان‌ها