این راهنما نحوه ایجاد یک متغیر ورودی را توضیح می‌دهد.
برای اجرا، مراحل به اطلاعات خاصی نیاز دارند. به عنوان مثال، ارسال ایمیل به یک آدرس ایمیل نیاز دارد. برای ارائه این اطلاعات لازم به مراحل، متغیرهای ورودی را تعریف کنید. پس از تعریف، متغیرهای ورودی معمولاً توسط کاربر در کارت پیکربندی مرحله تنظیم می‌شوند، در حالی که کاربر مرحله را تنظیم می‌کند.
متغیر ورودی را در دو جا تعریف کنید: فایل مانیفست افزونه، و در کدی با یک کارت پیکربندی که کاربران می‌توانند مقادیر متغیرهای ورودی را در آن وارد کنند.
متغیر ورودی را در فایل مانیفست تعریف کنید
در فایل مانیفست، متغیرهای ورودی را با آرایه inputs[] مشخص کنید. هر آیتم در آرایه inputs[] دارای این ویژگی‌ها است:
-
id: شناسه منحصر به فرد برای یک متغیر ورودی. برای اینکه جریان بتواند یک عنصر ورودی کارت پیکربندی را با این متغیر ورودی مرتبط کند، باید با نام عنصر کارت مربوطه مطابقت داشته باشد. -
description: توضیحی در مورد متغیر ورودی که قرار است به کاربران نهایی نمایش داده شود. -
cardinality: چند مقدار مجاز است. مقادیر ممکن عبارتند از:-
SINGLE: فقط یک مقدار مجاز است.
-
-
dataType: نوع مقادیر پذیرفته شده.dataTypeدارای ویژگیbasicTypeاست که نوع داده را تعریف می‌کند. مقادیر معتبر عبارتند از:-
STRING: یک رشته الفبایی-عددی. -
INTEGER: یک عدد. -
TIMESTAMP: یک مهر زمانی در قالب ISO 8601. برای مثال، در ISO 8601، 15 مارس 2025 به صورت 2025-03-15 نمایش داده می‌شود. -
BOOLEAN: یا درست است یا غلط. -
EMAIL_ADDRESS: یک آدرس ایمیل با فرمتdana@example.com.
-
مثال زیر سه متغیر ورودی برای یک مرحله ماشین حساب تعریف می‌کند. دو متغیر ورودی اول اعداد صحیح هستند و سومی یک عملیات حسابی است.
جی‌سون
{
"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"
}
}
]
}
}
}
متغیر ورودی را در کد تعریف کنید
کد این مرحله شامل تابعی به نام onConfigFunction() است که یک کارت پیکربندی را برمی‌گرداند که یک ویجت کارت ورودی را برای هر متغیر ورودی تعریف شده در آرایه inputs[] فایل مانیفست تعریف می‌کند.
ویجت‌های ورودی تعریف‌شده در کارت پیکربندی، الزامات زیر را دارند:
-
nameهر ویجت ورودی بایدidمتغیر ورودی مربوطه در فایل مانیفست مطابقت داشته باشد. - عدد صحیح ویجت ورودی باید با
cardinalityمتغیر ورودی در فایل مانیفست مطابقت داشته باشد. - نوع داده‌ی ویجت ورودی باید با
dataTypeمتغیر ورودی در فایل مانیفست مطابقت داشته باشد. اگر نوعdataTypeمتغیر ورودی عدد صحیح باشد، نمی‌تواند رشته را در خود نگه دارد.
برای کمک به ساخت رابط‌های کارت، به یکی از این گزینه‌ها مراجعه کنید:
- سازنده کارت : ابزاری تعاملی که می‌توانید برای ساخت و تعریف کارت‌ها از آن استفاده کنید.
- کارت : در مستندات مرجع API افزونه‌ی Google Workspace.
- سرویس کارت : یک سرویس اسکریپت برنامه‌ها که به اسکریپت‌ها اجازه می‌دهد کارت‌ها را پیکربندی و بسازند.
- نمای کلی رابط‌های مبتنی بر کارت : در مستندات توسعه‌دهنده افزونه Google Workspace.
مثال زیر یک کارت پیکربندی برای هر ویجت ورودی تعریف شده در متغیر ورودی تعریف شده در فایل مانیفست برمی‌گرداند.
اسکریپت برنامه‌ها
/**
* 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 card also includes a "Save"
* button to save the step configuration for the workflow.
*
* The input fields are configured to let the user select outputs from previous
* workflow steps as input values using the `hostAppDataSource` property.
*/
function onConfigFunction() {
var card = {
"sections": [
{
"header": "Step example: Calculate",
"widgets": [
{
"textInput": {
"name": "value1", // "name" must match an "id" in the manifest file's inputs[] array.
"label": "First value",
"hostAppDataSource" : {
"workflowDataSource" : {
"includeVariables" : true
}
}
}
},
{
"selectionInput": {
"name": "operation", // "name" must match an "id" in the manifest file's inputs[] array.
"label": "Operation",
"type": "DROPDOWN",
"items": [
{
"text": "+",
"value": "+",
},
{
"text": "-",
"value": "-",
},
{
"text": "x",
"value": "x",
},
{
"text": "/",
"value": "/",
}
]
}
},
{
"textInput": {
"name": "value2", // "name" must match an "id" in the manifest file's inputs[] array.
"label": "Second value",
"hostAppDataSource" : {
"workflowDataSource" : {
"includeVariables" : true
}
}
}
}
]
}
]
};
return {
"action": {
"navigations": [{
"push_card": card
}]
}
};
}
اعتبارسنجی متغیر ورودی
به عنوان بهترین روش، اعتبارسنجی کنید که کاربر مقدار مناسبی وارد کند. به بخش اعتبارسنجی متغیر ورودی مراجعه کنید.