Giriş değişkeniyle veri toplama

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

Adımların çalışması için belirli bilgiler gerekir. Örneğin, e-posta göndermek için e-posta adresi gerekir. Bu gerekli bilgileri sağlamak için giriş değişkenlerini tanımlayın. Tanımlandıktan sonra giriş değişkenleri genellikle kullanıcı tarafından adımın yapılandırma kartında, adım ayarlanırken belirlenir.

Giriş değişkenini iki yerde tanımlayın: eklentinin manifest dosyasında ve kullanıcıların giriş değişkenleri için değer girebileceği bir yapılandırma kartıyla birlikte kodda.

Giriş değişkenini manifest dosyasında tanımlayın

Manifest dosyasında, giriş değişkenlerini inputs[] dizisiyle belirtin. inputs[] dizisindeki her öğe şu özelliklere sahiptir:

  • id: Giriş değişkeninin benzersiz tanımlayıcısı. Akışın bir yapılandırma kartı giriş öğesini bu giriş değişkeniyle ilişkilendirmesine izin vermek için ilgili kart öğesinin adıyla eşleşmelidir.
  • description: Son kullanıcılara gösterilecek giriş değişkeninin açıklaması.
  • cardinality: Kaç değere izin verilir? Olası değerler:
    • SINGLE: Yalnızca bir değere izin verilir.
  • dataType: Kabul edilen değer türü. dataType, veri türünü tanımlayan basicType özelliğine sahiptir. Geçerli değerler şunlardır:
    • STRING: Alfanümerik bir dize.
    • INTEGER: Bir sayı.
    • TIMESTAMP: ISO 8601 biçiminde bir zaman damgası. Örneğin, ISO 8601'de 15 Mart 2025, 2025-03-15 olarak gösterilir.
    • BOOLEAN: Doğru veya yanlış.
    • EMAIL_ADDRESS: dana@example.com biçiminde bir e-posta adresi.

Aşağıdaki örnekte bir hesap makinesi adımı için üç giriş değişkeni tanımlanmaktadır. İlk iki giriş değişkeni tam sayı, üçüncü değişken ise aritmetik işlemdir.

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

Giriş değişkenini kodda tanımlama

Adımın kodu, manifest dosyasının inputs[] dizisinde tanımlanan her giriş değişkeni için bir giriş kartı widget'ı tanımlayan bir yapılandırma kartı döndüren onConfigFunction() adlı bir işlev içerir.

Yapılandırma kartında tanımlanan giriş widget'ları aşağıdaki koşulları karşılamalıdır:

  • Her giriş widget'ının name, manifest dosyasındaki ilgili giriş değişkeninin id ile eşleşmelidir.
  • Giriş widget'ının kardinalitesi, manifest dosyasındaki giriş değişkeninin cardinality ile eşleşmelidir.
  • Giriş widget'ının veri türü, giriş değişkeninin dataType ile eşleşmelidir. Giriş değişkeninin dataType değeri tamsayı ise dize tutamaz.

Kart arayüzleri oluşturma konusunda yardım almak için aşağıdaki seçeneklerden birine bakın:

  • Kart Oluşturucu: Kart oluşturmak ve tanımlamak için kullanabileceğiniz etkileşimli bir araçtır.
  • Card: Google Workspace eklenti API'si referans belgelerinde.
  • Card Service: Komut dosyalarının kartları yapılandırmasına ve oluşturmasına olanak tanıyan bir Apps Script hizmetidir.
  • Kart tabanlı arayüzlere genel bakış: Google Workspace eklenti geliştirici dokümanlarında.

Aşağıdaki örnekte, Define the input variable in the manifest file (Giriş değişkenini manifest dosyasında tanımlama) bölümünde tanımlanan her giriş widget'ı için bir yapılandırma kartı döndürülmektedir.

Apps Komut Dosyası

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

Giriş değişkenini doğrulama

En iyi uygulama olarak, kullanıcının uygun bir değer girdiğini doğrulayın. Giriş değişkenini doğrulama başlıklı makaleyi inceleyin.