إنشاء خطوة

يوضّح هذا الدليل كيفية إنشاء خطوة يمكن للمستخدمين إضافتها إلى وكيل في 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": "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() يجب أن تعرض جميع النتائج المحدّدة في بيان الوكيل، وإلا سيحدث خطأ.

يتضمّن نموذج الرمز البرمجي هذا دالة مساعِدة، 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. افتح مشروع البرنامج النصي في محرِّر Apps Script.
   2. انقر على نشر > اختبار عمليات النشر.
   3. انقر على تثبيت.
   4. في أسفل الصفحة، انقر على تم.

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

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

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

2. افتح "الوكلاء".

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

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

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

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

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

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