Giriş değişkenini doğrulama

Gemini alfa programı: Flows, Gemini alfa programı kapsamında kullanılabilir.

Bu kılavuzda, giriş değişkeninin nasıl doğrulanacağı açıklanmaktadır.

Bir giriş değişkeni tanımlarken en iyi uygulama olarak kullanıcının uygun bir değer girdiğini doğrulayın. Örneğin, kullanıcıdan bir rakam girmesini istiyorsanız a yerine 1 girdiğini doğrulayarak adımınızın hatasız çalıştığını doğrulayabilirsiniz.

Giriş değişkenlerini doğrulamanın iki yolu vardır:

• İstemci tarafı doğrulama: İstemci tarafı doğrulama ile kullanıcının girişini doğrudan cihazında doğrulayabilirsiniz. Kullanıcı anında geri bildirim alır ve adımı yapılandırırken girişindeki hataları düzeltebilir.
• Sunucu tarafı doğrulama: Sunucu tarafı doğrulama, doğrulama sırasında sunucuda mantık çalıştırmanıza olanak tanır. Bu, istemcinin sahip olmadığı bilgileri (ör. diğer sistemlerdeki veya veritabanlarındaki veriler) aramanız gerektiğinde kullanışlıdır.

İstemci tarafı doğrulama

İstemci tarafı doğrulama iki şekilde uygulanabilir:

• Bir widget'ın belirli bir karakter sayısından daha az karakter içerdiğini veya @ sembolünü içerdiğini doğrulama gibi temel doğrulama için Google Workspace eklentisinin Kart hizmetinin Validation sınıfını çağırın.
• Widget değerlerini diğer widget değerleriyle karşılaştırma gibi güçlü doğrulama için CardService kullanarak aşağıdaki desteklenen kart widget'larına Common Expression Language (CEL) doğrulaması ekleyebilirsiniz.

Validation sınıfını çağırma

Aşağıdaki örnek, bir TextInput widget'ının 10 veya daha az karakter içerdiğini doğrular:

Apps Komut Dosyası

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

Ek doğrulama seçenekleri için CEL doğrulamasını kullanın.

CEL Doğrulaması

Common Expression Language (CEL) doğrulama, diğer hizmetlerden veri aramaya bağlı olmayan giriş değeri kontrollerini istemci tarafına yükleyerek sunucu tarafı doğrulamanın gecikmesi olmadan anında giriş kontrolleri sunar.

Doğrulama sonucuna bağlı olarak widget'ı gösterme veya gizleme gibi kart davranışları oluşturmak için de CEL'i kullanabilirsiniz. Bu tür davranışlar, kullanıcının girişlerini düzeltmesine yardımcı olan bir hata mesajını göstermek veya gizlemek için kullanışlıdır.

Tam bir CEL doğrulama oluşturmak için aşağıdaki bileşenler gerekir:

• Karttaki ExpressionData: Tanımlanan koşullardan biri karşılandığında belirtilen doğrulama mantığını ve widget tetikleme mantığını içerir.

  • Id: Geçerli karttaki ExpressionData için benzersiz bir tanımlayıcı.
  • Expression: Doğrulama mantığını tanımlayan CEL dizesi (ör. "value1 == value2").
  • Conditions: Önceden tanımlanmış doğrulama sonuçlarının (BAŞARILI veya BAŞARISIZ) bir seçimini içeren koşullar listesi. Koşullar, ortak bir actionRuleId ile Triggers üzerinden widget tarafındaki EventAction ile ilişkilendirilir.
  • Kart düzeyinde EventAction: Kartta CEL doğrulamalarını etkinleştirir ve etkinlik sonrası tetikleyiciler aracılığıyla ExpressionData alanını sonuç widget'larıyla ilişkilendirir.
    • actionRuleId: Bu EventAction için benzersiz kimlik.
    • ExpressionDataAction: Bu işlemin CEL değerlendirmesini başlattığını belirtmek için START_EXPRESSION_EVALUATION olarak ayarlayın.
    • Trigger: Conditions öğesini actionRuleId temelinde Widget tarafındaki EventActions öğesine bağlar.

• Widget düzeyinde EventAction: Başarı veya başarısızlık koşulu karşılandığında sonuç widget'ının davranışını kontrol eder. Örneğin, bir sonuç widget'ı, yalnızca doğrulama başarısız olduğunda görünür hale gelen bir hata mesajı içeren bir TextParagraph olabilir.

  • actionRuleId: Kart tarafındaki Trigger ile actionRuleId eşleşir.
  • CommonWidgetAction: Widget görünürlüğünü güncelleme gibi değerlendirme içermeyen işlemleri tanımlar.
    • UpdateVisibilityAction: Bir widget'ın görünürlük durumunu (VISIBLE veya HIDDEN) güncelleyen bir işlem.

Aşağıdaki örnekte, iki metin girişinin eşit olup olmadığını kontrol etmek için CEL doğrulamasının nasıl uygulanacağı gösterilmektedir. Eşit değillerse hata mesajı gösterilir.

• 

  Şekil 1: failCondition karşılandığında (girişler eşit olmadığında) hata mesajı widget'ı VISIBLE olarak ayarlanır ve görünür.

• 

  Şekil 2: successCondition karşılandığında (girişler eşit olduğunda) hata mesajı widget'ı HIDDEN olarak ayarlanır ve görünmez.

Örnek uygulama kodu ve JSON manifest dosyası:

Apps Komut Dosyası

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 manifest dosyası

{
  "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"
          }
        }
      ]
    }
  }
}

Not: Metin girişlerinin fieldName, manifest dosyasındaki inputs alanında tanımlanan id ile eşleşmelidir. Daha fazla bilgi için Giriş değişkenini manifest dosyasında tanımlama başlıklı makaleye bakın.

Desteklenen CEL doğrulama widget'ları ve işlemleri

CEL doğrulamasını destekleyen kart widget'ları

Aşağıdaki widget'lar CEL doğrulamasını destekler:

• TextInput
• SelectionInput
• DateTimePicker

Desteklenen CEL doğrulama işlemleri

• Aritmetik işlemler
  • +: İki int64, uint64 veya double sayısı ekler.
  • -: İki int64, uint64 veya double sayısını çıkarır.
  • *: İki int64, uint64 veya double sayısını çarpar.
  • /: İki int64, uint64 veya double sayısını böler (tam sayı bölme).
  • %: İki int64 veya uint64 sayının modülünü hesaplar.
  • -: int64 veya uint64 sayısını olumsuzlar.
• Mantıksal işlemler:
  • &&: İki Boole değeri üzerinde mantıksal AND işlemi gerçekleştirir.
  • ||: İki Boole değeri üzerinde mantıksal OR işlemi gerçekleştirir.
  • !: Boole değeri üzerinde mantıksal NOT işlemi gerçekleştirir.
• Karşılaştırma İşlemleri:
  • ==: İki değerin eşit olup olmadığını kontrol eder. Sayılar ve listeler desteklenir.
  • !=: İki değerin eşit olup olmadığını kontrol eder. Sayılar ve listeler desteklenir.
  • <: İlk int64, uint64 veya double sayısının ikinciden küçük olup olmadığını kontrol eder.
  • <=: İlk int64, uint64 veya double sayısının ikinciden küçük ya da ona eşit olup olmadığını kontrol eder.
  • >: İlk int64, uint64 veya double sayısının ikinciden büyük olup olmadığını kontrol eder.
  • >=: İlk int64, uint64 veya double sayısının ikinciden büyük ya da ona eşit olup olmadığını kontrol eder.
• Listeleme İşlemleri:
  • in: Bir değerin listede olup olmadığını kontrol eder. Sayıları, dizeleri ve iç içe geçmiş listeleri destekler.
  • size: Bir listedeki öğe sayısını döndürür. Sayıları ve iç içe geçmiş listeleri destekler.

Desteklenmeyen CEL doğrulama senaryoları

• İkili işlemler için yanlış bağımsız değişken boyutları: İkili işlemler (örneğin, add_int64, eşittir) tam olarak iki bağımsız değişken gerektirir. Farklı sayıda bağımsız değişken sağlamak hataya neden olur.
• Tekli İşlemler İçin Yanlış Bağımsız Değişken Boyutları: Tekli işlemler (ör. negate_int64) için tam olarak bir bağımsız değişken gerekir. Farklı sayıda bağımsız değişken sağlamak hataya neden olur.
• Sayısal İşlemlerde Desteklenmeyen Türler: Sayısal ikili ve tekli işlemler yalnızca sayı bağımsız değişkenlerini kabul eder. Diğer türlerin (örneğin, boolean) sağlanması hataya neden olur.

Sunucu tarafı doğrulama

Sunucu tarafı doğrulama ile adımınızın kodunda onSaveFunction() belirterek sunucu tarafı mantığı çalıştırabilirsiniz. Kullanıcı, adımın yapılandırma kartından uzaklaştığında onSaveFunction() çalışır ve kullanıcının girişini doğrulamanıza olanak tanır.

Kullanıcının girişi geçerliyse saveWorkflowAction değerini döndürün.

Kullanıcının girişi geçersizse kullanıcıya hatanın nasıl çözüleceğini açıklayan bir hata mesajı gösteren bir yapılandırma kartı döndürün.

Sunucu tarafı doğrulama eşzamansız olduğundan kullanıcı, akışını yayınlayana kadar giriş hatası hakkında bilgi sahibi olmayabilir.

Manifest dosyasındaki her doğrulanmış girişin id değeri, kodda bir kart widget'ının name değeriyle eşleşmelidir.

Aşağıdaki örnekte, kullanıcı metin girişinin "@" işaretini içerdiği doğrulanır:

Manifest dosyası

Manifest dosyası alıntısında, "onSave" adlı bir onSaveFunction() belirtiliyor:

JSON

{
  "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"
          }
        }
      ]
    }
  }
}

Uygulama kodu

Adımın kodu, onSave() adlı bir işlev içeriyor. Kullanıcı tarafından girilen bir dizenin @ içerip içermediğini doğrular. İçeriyorsa akış adımını kaydeder. Aksi takdirde, hatanın nasıl düzeltileceğini açıklayan bir hata mesajı içeren yapılandırma kartı döndürülür.

Apps Komut Dosyası

/**
 * 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);
  }
}

İlgili konular

• Giriş değişkeni tanımlama
• Etkinlikleri ve hataları günlüğe kaydetme
• Flows etkinlik nesnesi
• Common Expression Language (CEL)