إنشاء خطوة

معاينة محدودة: تتوفّر معاينة محدودة لميزة توسيع 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. يتم تمرير أي قيم إدخال ضبطها المستخدم أثناء الإعداد كما هو محدّد في onConfigFunction إلى onExecuteFunction.

   اكتب onExecuteFunction بحيث تنفّذ مهمتها بشكل متزامن باستخدام المدخلات المقدَّمة. يجب أن تعرض onExecuteFunction جميع المخرجات المحدّدة في بيان المسار، وإلا سيحدث خطأ.

تتضمّن عينة التعليمات البرمجية هذه دالة داعمة، هي outputVariables، التي تنشئ المتغيّرات المقدَّمة وترسلها كناتج من الخطوة.

أصبحت خطوتك جاهزة للاختبار.

في ما يلي رمز خطوة الآلة الحاسبة:

برمجة التطبيقات

/**
 * 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. افتح مشروع النص البرمجي في محرّر برمجة التطبيقات.
   2. انقر على نشر > عمليات النشر التجريبية.
   3. انقر على تثبيت.
   4. في أسفل الشاشة، انقر على تم.

   يمكنك السماح لمستخدمين آخرين باختبار الإضافة من خلال مشاركة مشروع برمجة تطبيقات مع حساباتهم (يجب منحهم إذن التعديل). بعد ذلك، اطلب من المستخدمين اتّباع الخطوات السابقة.

   بعد تثبيت الإضافة، تصبح متاحة على الفور في "المسارات". قد تحتاج إلى إعادة تحميل "المسارات" قبل ظهور الإضافة. يجب أيضًا منح الإذن للإضافة قبل استخدامها.

   لمزيد من المعلومات عن عمليات النشر التجريبية، يمكنك الاطّلاع على مقالة تثبيت إضافة غير منشورة.

2. افتح "المسارات".

3. أنشئ مسارًا يتضمّن خطوتك:

   1. انقر على مسار جديد.
   2. اختَر طريقة بدء المسار. عند اختبار خطوة، من المستحسن اختيار أداة بدء يمكنك تشغيلها بنفسك، مثل إرسال رسالة إلكترونية إلى نفسك. إذا كانت خطوتك تتطلّب متغيّر إدخال، اضبط متغيّر الإدخال كجزء من ناتج أداة البدء.
   3. انقر على إضافة خطوة. اختَر الخطوة التي أنشأتها أو عدّلتها، والتي يُطلق عليها اسم الحساب.
   4. اضبط خطوتك. بالنسبة إلى خطوة الحساب، اختَر قيمتين وعملية حسابية. يتم حفظ الخطوة تلقائيًا.
   5. لاختبار ناتج خطوتك، أضِف خطوة أخرى. على سبيل المثال، لإضافة ناتج إلى رسالة إلكترونية، يمكنك إضافة خطوة إرسال رسالة في Gmail. في الرسالة، انقر على المتغيّرات واختَر ناتج خطوتك. بالنسبة إلى خطوة الحساب، انقر على "إضافة" المتغيّرات > الخطوة 2: النتيجة المحسوبة > النتيجة المحسوبة. يظهر المتغيّر على شكل شريحة في حقل الرسالة.
   6. انقر على تفعيل. أصبح المسار جاهزًا للتشغيل.

4. شغِّل المسار عن طريق تشغيل أداة البدء الخاصة به. على سبيل المثال، إذا كان المسار يبدأ عند تلقّي رسالة إلكترونية، أرسِل رسالة إلكترونية إلى نفسك.

5. تأكَّد من تشغيل المسار على النحو المتوقّع. يمكنك الاطّلاع على السجلات من خلال الانتقال إلى علامة التبويب النشاط في أداة إنشاء المسار. لمعرفة كيفية إنشاء سجلات مخصّصة في علامة التبويب "النشاط"، يمكنك الاطّلاع على مقالة سجلات النشاط.

مواضيع ذات صلة

• متغيّرات الإدخال
• التحقّق من صحة متغيّر إدخال
• متغيّرات الناتج
• تحديد مورد مخصّص
• المتغيّرات الديناميكية
• تسجيل النشاط والأخطاء
• كائنات أحداث Workspace Studio