ساختن مرحله

این راهنما توضیح می‌دهد که چگونه گامی ایجاد کنید که کاربران بتوانند به جریانی در Google Workspace Studio اضافه کنند.

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

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

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

برای ساختن مرحله، آن را در فایل مانیفست برافزا پیکربندی کنید، منطق برنامه را در کد برافزای 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 با حساب کاربران دیگر، به آن‌ها اجازه دهید برافزا را آزمایش کنند (دسترسی ویرایش لازم است). سپس از کاربران بخواهید مراحل قبلی را دنبال کنند.

    پس‌از نصب، برافزا بلافاصله در «جریان‌ها» دردسترس قرار می‌گیرد. ممکن است لازم باشد جریان‌ها را پیش‌از ظاهر شدن برافزا بازآوری کنید. همچنین باید پیش‌از استفاده از این برافزا، آن را مجاز کنید.

    برای کسب اطلاعات بیشتر درباره استقرار آزمایشی، به نصب برافزای منتشرنشده مراجعه کنید.

  2. ‫Flows را باز کنید.

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

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

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

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