ساخت یک پله

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2. نمایندگان باز.

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

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

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

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

مباحث مرتبط

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