إنشاء خطوة

يشرح هذا الدليل كيفية إنشاء خطوة يمكن للمستخدمين إضافتها إلى سير عمل في 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
    },
    "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، تنشئ المتغيّرات المقدَّمة وترسلها كناتج من الخطوة.

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

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

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

/**
 * 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
• درس تطبيقي حول الترميز: إنشاء خطوات مخصّصة للمشغّلات والإجراءات في Workspace Studio
• درس تطبيقي حول الترميز: إنشاء خطوات إجراءات ومفاتيح تشغيل مخصّصة في Workspace Studio باستخدام Node.js