يوضّح هذا الدليل كيفية إنشاء خطوة يمكن للمستخدمين إضافتها إلى مسار في Google Workspace Studio.
الخطوة هي خطوة واحدة في تسلسل مهام سير العمل. لا يمكن للخطوات بدء مسار.
على سبيل المثال، لنفترض أنّ هناك خطوة تتضمّن عمليات حسابية. تطلب من المستخدم إدخال قيمتين وعملية حسابية. ثم تجري العملية الحسابية على القيم وتعرض النتيجة.
لإنشاء خطوة، عليك ضبطها في ملف بيان الإضافة، وكتابة منطق التطبيق في رمز إضافة Google Workspace، ثم نشر الخطوة واختبارها.
تحديد الخطوة
لضبط إعدادات خطوة، عليك تحديدها في ملف البيان وكتابة منطق التطبيق الخاص بها في الرمز.
تحديد الخطوة في ملف البيان
في ملف البيان، appsscript.json:
- اضبط
onConfigFunctionوonExecuteFunctionعلى أسماء الدوال المقابلة في رمز الإضافة. في هذا المثال، يُطلق على الدالتين الاسمانonConfigCalculate()وonExecuteCalculate().- تتولّى
onConfigFunctionإعداد الخطوة وضبطها. إذا لزم الأمر، يجمع بيانات من المستخدمين ضرورية لتنفيذ الخطوة، مثل العنوان الذي سيتم إرسال رسالة إلكترونية إليه. في مثال هذا الدليل، نطلب قيمتين وعملية حسابية. - ينفّذ
onExecuteFunctionالخطوة. إذا تم جمع البيانات من المستخدمين، يتم تمرير هذه البيانات إلى هذه الدالة. تعرض هذه السمة مخرجات، إذا كان ذلك منطبقًا. في مثال هذا الدليل، يتم عرض نتيجة عملية حسابية.
- تتولّى
اضبط المدخلات والمخرجات المطلوبة، ما يتيح للخطوة جمع البيانات وإرسالها إلى الخطوات اللاحقة. في هذا المثال، اطلب من المستخدم إدخال قيمتين وعملية رياضية محدّدة في
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"
}
}
]
}
}
}
بعد ذلك، اكتب الرمز البرمجي الداعم عن طريق تحديد الخطوة في الرمز البرمجي.
تحديد الخطوة في الرمز البرمجي
في الرمز البرمجي للتطبيق، اتّبِع الخطوات التالية:
اكتب
onConfigFunction، ويُطلق عليهonConfigCalculate()في هذا المثال. عندما يضيف المستخدمون الخطوة إلى مسار، يمكنهم ضبط جوانب الخطوة في أداة إنشاء المسارات. لجمع المعلومات المطلوبة من المستخدم، يحدّدonConfigFunctionبطاقة إعداد.البطاقات هي اللبنات الأساسية لواجهات المستخدم في الإضافات. تتيح البطاقات استخدام تنسيق محدّد وعناصر تفاعلية في واجهة المستخدم، مثل الأزرار، بالإضافة إلى الوسائط التفاعلية المتقدّمة، مثل الصور. البطاقات هي الطريقة التي يمكنك من خلالها الحصول على بيانات من مستخدم يحتاج إلى تنفيذ الخطوة، مثل عنوان بريد إلكتروني لإرسال رسالة إلكترونية.
تعرض الدالة
OnConfigFunctionبطاقة. تحدّد هذه البطاقة واجهة المستخدم التي يضبط فيها المستخدمون بيانات الخطوة. في هذا المثال، ينشئonConfigFunctionبطاقة تطلب من المستخدم إدخال قيمتين وعملية حسابية.اكتب
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);
}
اختبار الخطوة
لاختبار خطوتك، عليك إعداد عملية نشر تجريبية للإضافة، وإضافة الخطوة إلى مسار، ثم تشغيل المسار.
إعداد عملية نشر تجريبية للإضافة:
- افتح مشروع برمجة تطبيقات في أداة تعديل النصوص البرمجية.
- انقر على نشر > اختبار عمليات النشر.
- انقر على تثبيت.
- في أسفل الصفحة، انقر على تم.
يمكنك السماح لمستخدمين آخرين باختبار الإضافة من خلال مشاركة مشروع برمجة تطبيقات مع حساباتهم (يجب منحهم إذن التعديل). بعد ذلك، اطلب من المستخدمين اتّباع الخطوات السابقة.
بعد تثبيت الوظيفة الإضافية، ستتوفّر على الفور في "سير العمل". قد تحتاج إلى إعادة تحميل "المخططات" قبل ظهور الإضافة. يجب أيضًا تفويض الإضافة قبل استخدامها.
لمزيد من المعلومات عن عمليات النشر التجريبية، اطّلِع على تثبيت إضافة غير منشورة.
افتح "المسارات".
أنشئ تدفقًا يتضمّن خطوتك:
- انقر على تدفق جديد.
- اختَر طريقة بدء المسار. عند اختبار خطوة، من الأفضل اختيار مشغّل يمكنك إعداده بنفسك، مثل إرسال رسالة إلكترونية إلى نفسك. إذا كانت خطوتك تتطلّب متغيّر إدخال، اضبط متغيّر الإدخال كجزء من ناتج المشغّل.
- انقر على إضافة خطوة. اختَر الخطوة التي أنشأتها أو عدّلتها، والتي تُسمى الحساب.
- اضبط الخطوة. بالنسبة إلى خطوة الحساب، اختَر قيمتَين وعملية حسابية. يتم حفظ الخطوة تلقائيًا.
- لاختبار ناتج الخطوة، أضِف خطوة أخرى. على سبيل المثال، لإضافة ناتج إلى رسالة إلكترونية، يمكنك إضافة خطوة إرسال رسالة في Gmail. في الرسالة، انقر على المتغيرات واختَر ناتج الخطوة. بالنسبة إلى خطوة الحساب، اختَر المتغيّرات > الخطوة 2: النتيجة المحسوبة > النتيجة المحسوبة. يظهر المتغيّر على شكل شريحة في حقل الرسالة.
- انقر على تفعيل. أصبح المسار جاهزًا للتنفيذ.
شغِّل المسار من خلال تفعيل إجراء التفعيل الخاص به. على سبيل المثال، إذا كان مسارك يبدأ عند تلقّي رسالة إلكترونية، أرسِل رسالة إلكترونية إلى نفسك.
تأكَّد من أنّ المسار يعمل على النحو المتوقّع. يمكنك الاطّلاع على السجلات من خلال الانتقال إلى علامة التبويب النشاط في "أداة إنشاء المسارات". لمعرفة كيفية إنشاء سجلّات مخصّصة في علامة التبويب "النشاط"، اطّلِع على سجلّات الأنشطة.
مواضيع ذات صلة
- متغيّرات الإدخال
- التحقّق من صحة متغيّر إدخال
- متغيّرات الناتج
- تحديد مورد مخصّص
- المتغيرات الديناميكية
- تسجيل النشاط والأخطاء
- عناصر أحداث Workspace Studio