اعتبارسنجی یک متغیر ورودی

برنامه آلفای جمینی: فلوز به عنوان بخشی از برنامه آلفای جمینی در دسترس است.

این راهنما نحوه اعتبارسنجی یک متغیر ورودی را توضیح می‌دهد.

هنگام تعریف یک متغیر ورودی، به عنوان بهترین روش، اعتبارسنجی کنید که کاربر مقدار مناسبی را وارد کند. برای مثال، اگر از کاربر می‌خواهید یک عدد وارد کند، تأیید کنید که آنها به جای a 1 وارد می‌کنند، تأیید می‌کند که مرحله شما بدون خطا اجرا می‌شود.

دو روش برای اعتبارسنجی یک متغیر ورودی وجود دارد:

• اعتبارسنجی سمت کلاینت : با اعتبارسنجی سمت کلاینت، ورودی کاربر را مستقیماً روی دستگاه او تأیید می‌کنید. کاربر بازخورد فوری دریافت می‌کند و می‌تواند هرگونه خطایی را در ورودی خود هنگام پیکربندی مرحله اصلاح کند.
• اعتبارسنجی سمت سرور : اعتبارسنجی سمت سرور به شما امکان می‌دهد در طول اعتبارسنجی، منطق را روی سرور اجرا کنید، که زمانی مفید است که نیاز به جستجوی اطلاعاتی دارید که کلاینت ندارد، مانند داده‌های موجود در سیستم‌های دیگر یا پایگاه‌های داده.

اعتبارسنجی سمت کلاینت

دو روش برای پیاده‌سازی اعتبارسنجی سمت کلاینت وجود دارد:

• برای اعتبارسنجی اولیه، مانند تأیید اینکه یک ویجت کمتر از تعداد مشخصی کاراکتر دارد یا حاوی نماد @ است، کلاس Validation از سرویس Card افزونه‌ی Google Workspace را فراخوانی کنید.
• برای اعتبارسنجی قوی، مانند مقایسه مقادیر ویجت با سایر مقادیر ویجت، می‌توانید اعتبارسنجی زبان عبارات مشترک (CEL) را با استفاده از CardService به ویجت‌های کارت پشتیبانی‌شده زیر اضافه کنید.

کلاس Validation را فراخوانی کنید

مثال زیر تأیید می‌کند که یک ویجت TextInput شامل ۱۰ کاراکتر یا کمتر است:

اسکریپت برنامه‌ها

const validation = CardService.newValidation().setCharacterLimit('10').setInputType(
    CardService.InputType.TEXT);

برای گزینه‌های اعتبارسنجی بیشتر، از اعتبارسنجی CEL استفاده کنید.

اعتبارسنجی CEL

اعتبارسنجی زبان عبارات مشترک (CEL) با انتقال بررسی‌های مقدار ورودی که به جستجوی داده‌ها از سایر سرویس‌ها به سمت کلاینت وابسته نیستند، بررسی‌های ورودی فوری را بدون تأخیر اعتبارسنجی سمت سرور ارائه می‌دهد.

همچنین می‌توانید از CEL برای ایجاد رفتارهای کارت، مانند نمایش یا پنهان کردن یک ویجت بسته به نتیجه اعتبارسنجی، استفاده کنید. این نوع رفتار برای نمایش یا پنهان کردن پیام خطایی که به کاربران کمک می‌کند ورودی‌های خود را اصلاح کنند، مفید است.

ساخت یک اعتبارسنجی کامل CEL شامل اجزای زیر است:

• ExpressionData در Card: شامل منطق اعتبارسنجی مشخص شده و منطق فعال‌سازی ویجت در صورت برآورده شدن یکی از شرایط تعریف شده است.

  • Id : یک شناسه منحصر به فرد برای ExpressionData در کارت فعلی.
  • Expression : رشته CEL که منطق اعتبارسنجی را تعریف می‌کند (مثلاً "value1 == value2" ).
  • Conditions : فهرستی از شرایط که شامل مجموعه‌ای از نتایج اعتبارسنجی از پیش تعریف‌شده (موفق یا ناموفق) است. شرایط از طریق Triggers با یک actionRuleId مشترک به EventAction سمت ویجت گره خورده‌اند.
  • EventAction در سطح کارت: اعتبارسنجی‌های CEL را در کارت فعال می‌کند و فیلد ExpressionData را از طریق تریگرهای پس از رویداد به ویجت‌های نتیجه مرتبط می‌سازد.
    • actionRuleId : شناسه منحصر به فرد برای این EventAction .
    • ExpressionDataAction : برای نشان دادن اینکه این اکشن ارزیابی CEL را شروع می‌کند، روی START_EXPRESSION_EVALUATION تنظیم کنید.
    • Trigger : Conditions بر اساس actionRuleId به EventActions سمت ویجت متصل می‌کند.

• EventAction در سطح ویجت: رفتار ویجت نتیجه را در صورت برآورده شدن شرط موفقیت یا شکست کنترل می‌کند. برای مثال، یک ویجت نتیجه می‌تواند یک TextParagraph باشد که حاوی یک پیام خطا است که فقط در صورت عدم موفقیت اعتبارسنجی قابل مشاهده است.

  • actionRuleId : با actionRuleId در Trigger سمت کارت مطابقت دارد.
  • CommonWidgetAction : اقداماتی را تعریف می‌کند که شامل ارزیابی نمی‌شوند، مانند به‌روزرسانی قابلیت مشاهده ویجت.
    • UpdateVisibilityAction : عملی که وضعیت نمایش ویجت (قابل مشاهده یا پنهان) را به‌روزرسانی می‌کند.

مثال زیر نحوه پیاده‌سازی اعتبارسنجی CEL را برای بررسی برابری دو ورودی متنی نشان می‌دهد. در صورت عدم برابری، یک پیام خطا نمایش داده می‌شود.

• 

  شکل ۱: وقتی failCondition برقرار باشد (ورودی‌ها برابر نباشند)، ویجت پیام خطا روی VISIBLE تنظیم شده و ظاهر می‌شود.

• 

  شکل ۲: وقتی successCondition برقرار باشد (ورودی‌ها برابر باشند)، ویجت پیام خطا روی HIDDEN تنظیم شده و نمایش داده نمی‌شود.

در اینجا کد برنامه نمونه و فایل مانیفست JSON آمده است:

اسکریپت برنامه‌ها

function onConfig() {

  // Create a Card
  let card = CardService.newCardBuilder();

  const textInput_1 = CardService.newTextInput()
    .setTitle("Input number 1")
    .setFieldName("value1"); // FieldName's value must match a corresponding ID defined in the inputs[] array in the manifest file.
  const textInput_2 = CardService.newTextInput()
    .setTitle("Input number 2")
    .setFieldName("value2"); // FieldName's value must match a corresponding ID defined in the inputs[] array in the manifest file.
  let sections = CardService.newCardSection()
    .setHeader("Two number equals")
    .addWidget(textInput_1)
    .addWidget(textInput_2);

  // CEL Validation

  // Define Conditions
  const condition_success = CardService.newCondition()
    .setActionRuleId("CEL_TEXTINPUT_SUCCESS_RULE_ID")
    .setExpressionDataCondition(
      CardService.newExpressionDataCondition()
      .setConditionType(
        CardService.ExpressionDataConditionType.EXPRESSION_EVALUATION_SUCCESS));
  const condition_fail = CardService.newCondition()
    .setActionRuleId("CEL_TEXTINPUT_FAILURE_RULE_ID")
    .setExpressionDataCondition(
      CardService.newExpressionDataCondition()
      .setConditionType(
        CardService.ExpressionDataConditionType.EXPRESSION_EVALUATION_FAILURE));

  // Define Card-side EventAction
  const expressionDataAction = CardService.newExpressionDataAction()
    .setActionType(
      CardService.ExpressionDataActionType.START_EXPRESSION_EVALUATION);
  // Define Triggers for each Condition respectively
  const trigger_success = CardService.newTrigger()
    .setActionRuleId("CEL_TEXTINPUT_SUCCESS_RULE_ID");
  const trigger_failure = CardService.newTrigger()
    .setActionRuleId("CEL_TEXTINPUT_FAILURE_RULE_ID");

  const eventAction = CardService.newEventAction()
    .setActionRuleId("CEL_TEXTINPUT_EVALUATION_RULE_ID")
    .setExpressionDataAction(expressionDataAction)
    .addPostEventTrigger(trigger_success)
    .addPostEventTrigger(trigger_failure);

  // Define ExpressionData for the current Card
  const expressionData = CardService.newExpressionData()
    .setId("expData_id")
    .setExpression("value1 == value2") // CEL expression
    .addCondition(condition_success)
    .addCondition(condition_fail)
    .addEventAction(eventAction);
  card = card.addExpressionData(expressionData);

  // Create Widget-side EventActions and a widget to display error message
  const widgetEventActionFail = CardService.newEventAction()
    .setActionRuleId("CEL_TEXTINPUT_FAILURE_RULE_ID")
    .setCommonWidgetAction(
      CardService.newCommonWidgetAction()
      .setUpdateVisibilityAction(
        CardService.newUpdateVisibilityAction()
        .setVisibility(
          CardService.Visibility.VISIBLE)));
  const widgetEventActionSuccess = CardService.newEventAction()
    .setActionRuleId("CEL_TEXTINPUT_SUCCESS_RULE_ID")
    .setCommonWidgetAction(
      CardService.newCommonWidgetAction()
      .setUpdateVisibilityAction(
        CardService.newUpdateVisibilityAction()
        .setVisibility(
          CardService.Visibility.HIDDEN)));
  const errorWidget = CardService.newTextParagraph()
    .setText("The first and second value must match.")
    .setVisibility(CardService.Visibility.HIDDEN) // Initially hidden
    .addEventAction(widgetEventActionFail)
    .addEventAction(widgetEventActionSuccess);
  sections = sections.addWidget(errorWidget);

  card = card.addSection(sections);
  // Build and return the Card
  return card.build();
}

فایل مانیفست JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "CEL validation example",
      "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": "CEL Demo",
          "description": "Demonstrates CEL Validation",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "The first number",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              },
              {
                "id": "value2",
                "description": "The second number",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "INTEGER"
                }
              }
            ],
            "onConfigFunction": "onConfig",
            "onExecuteFunction": "onExecute"
          }
        }
      ]
    }
  }
}

نکته: fieldName ورودی‌های متنی باید با id تعریف‌شده در فیلد inputs در فایل مانیفست مطابقت داشته باشد. برای کسب اطلاعات بیشتر، به بخش تعریف متغیر ورودی در فایل مانیفست مراجعه کنید.

ویجت‌ها و عملیات اعتبارسنجی CEL پشتیبانی‌شده

ابزارک‌های کارت که از اعتبارسنجی CEL پشتیبانی می‌کنند

ویجت‌های زیر از اعتبارسنجی CEL پشتیبانی می‌کنند:

• TextInput
• SelectionInput
• DateTimePicker

عملیات اعتبارسنجی CEL پشتیبانی شده

• عملیات حسابی
  • + : دو عدد int64 ، uint64 یا double را جمع می‌کند.
  • - : دو عدد int64 ، uint64 یا double را از هم کم می‌کند.
  • * : دو عدد int64 ، uint64 یا double در هم ضرب می‌کند.
  • / : دو عدد int64 ، uint64 یا double را بر هم تقسیم می‌کند (تقسیم عدد صحیح).
  • % : جمع دو عدد int64 یا uint64 را محاسبه می‌کند.
  • - : یک عدد int64 یا uint64 را منفی می‌کند.
• عملیات منطقی:
  • && : عملیات منطقی AND را روی دو مقدار بولی انجام می‌دهد.
  • || : یک عملیات منطقی OR روی دو مقدار بولی انجام می‌دهد.
  • ! : یک عملیات منطقی NOT را روی یک مقدار بولی انجام می‌دهد.
• عملیات مقایسه:
  • == : بررسی می‌کند که آیا دو مقدار با هم برابر هستند یا خیر. از اعداد و لیست‌ها پشتیبانی می‌کند.
  • != : بررسی می‌کند که آیا دو مقدار با هم برابر هستند یا خیر. از اعداد و لیست‌ها پشتیبانی می‌کند.
  • < : بررسی می‌کند که آیا عدد اول int64 ، uint64 یا double از عدد دوم کوچکتر است یا خیر.
  • <= : بررسی می‌کند که آیا عدد اول int64 ، uint64 یا double کوچکتر یا مساوی عدد دوم است یا خیر.
  • > : بررسی می‌کند که آیا عدد اول int64 ، uint64 یا double از عدد دوم بزرگتر است یا خیر.
  • >= : بررسی می‌کند که آیا عدد اول int64 ، uint64 یا double بزرگتر یا مساوی عدد دوم است یا خیر.
• عملیات لیست:
  • in : بررسی می‌کند که آیا مقداری در یک لیست وجود دارد یا خیر. از اعداد، رشته‌ها و لیست‌های تو در تو پشتیبانی می‌کند.
  • size : تعداد آیتم‌های موجود در یک لیست را برمی‌گرداند. از اعداد و لیست‌های تو در تو پشتیبانی می‌کند.

سناریوهای اعتبارسنجی CEL پشتیبانی نشده

• اندازه‌های نادرست آرگومان برای عملیات دودویی : عملیات دودویی (برای مثال، add_int64 ، equals) دقیقاً به دو آرگومان نیاز دارند. ارائه تعداد متفاوتی از آرگومان‌ها باعث ایجاد خطا می‌شود.
• اندازه‌های نادرست آرگومان برای عملیات یگانه : عملیات یگانه (برای مثال، negate_int64 ) دقیقاً به یک آرگومان نیاز دارد. ارائه تعداد متفاوتی از آرگومان‌ها باعث بروز خطا می‌شود.
• انواع پشتیبانی نشده در عملیات عددی : عملیات عددی دودویی و یگانی فقط آرگومان‌های عددی را می‌پذیرند. ارائه انواع دیگر (به عنوان مثال، بولی) باعث ایجاد خطا می‌شود.

اعتبارسنجی سمت سرور

با اعتبارسنجی سمت سرور، می‌توانید با مشخص کردن onSaveFunction() در کد مرحله خود، منطق سمت سرور را اجرا کنید. وقتی کاربر از کارت پیکربندی مرحله خارج می‌شود، onSaveFunction() اجرا می‌شود و به شما امکان می‌دهد ورودی کاربر را تأیید کنید.

اگر ورودی کاربر معتبر باشد، saveWorkflowAction برمی‌گرداند.

اگر ورودی کاربر نامعتبر است، یک کارت پیکربندی را برگردانید که یک پیام خطا را به کاربر نمایش می‌دهد و نحوه رفع خطا را توضیح می‌دهد.

از آنجا که اعتبارسنجی سمت سرور ناهمزمان است، ممکن است کاربر تا زمانی که جریان خود را منتشر نکند، از خطای ورودی مطلع نشود.

id هر ورودی اعتبارسنجی شده در فایل مانیفست باید با name ویجت کارت در کد مطابقت داشته باشد.

مثال زیر اعتبارسنجی می‌کند که ورودی متن کاربر شامل علامت "@" باشد:

فایل مانیفست

فایل مانیفست، یک تابع onSaveFunction() با نام "onSave" را مشخص می‌کند:

جی‌سون

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Server-side validation example",
      "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 an email address",
          "workflowAction": {
            "inputs": [
              {
                "id": "email",
                "description": "email address",
                "cardinality": "SINGLE",
                "required": true,
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigCalculate",
            "onExecuteFunction": "onExecuteCalculate",
            "onSaveFunction": "onSave"
          }
        }
      ]
    }
  }
}

کد برنامه

کد این مرحله شامل تابعی به نام onSave() است. این تابع اعتبارسنجی می‌کند که آیا رشته ورودی کاربر شامل @ است یا خیر. اگر این کار را انجام دهد، مرحله جریان را ذخیره می‌کند. اگر این کار را نکند، یک کارت پیکربندی به همراه یک پیام خطا که نحوه رفع خطا را توضیح می‌دهد، برمی‌گرداند.

اسکریپت برنامه‌ها

/**
 * Validates user input asynchronously when the user
 * navigates away from a step's configuration card.
*/
function onSave(event) {

  // "email" matches the input ID specified in the manifest file.
  var email = event.workflow.actionInvocation.inputs["email"];

  // Validate that the email address contains an "@" sign:
  if(email.includes("@")) {

  // If successfully validated, save and proceed.
    return {
      "hostAppAction" : {
        "workflowAction" : {
          "saveWorkflowAction" : {}
        }
      }
    };

  // If the input is invalid, return a card with an error message
  } else {

var card = {
    "sections": [
      {
        "header": "Collect Email",
        "widgets": [
          {
            "textInput": {
              "name": "email",
              "label": "email address",
              "hostAppDataSource" : {
                "workflowDataSource" : {
                  "includeVariables" : true
                }
              }
            }
          },
          {
            "textParagraph": {
              "text": "<b>Error:</b> Email addresses must include the '@' sign.",
              "maxLines": 1
            }
          }
        ]
      }
    ]
  };
  return pushCard(card);
  }
}

مباحث مرتبط

• تعریف یک متغیر ورودی
• ثبت فعالیت‌ها و خطاها
• شیء رویداد جریان‌ها
• زبان بیان مشترک (CEL)