Mengumpulkan data dengan variabel input

Panduan ini menjelaskan cara membuat variabel input.

Untuk dijalankan, langkah-langkah memerlukan informasi tertentu. Misalnya, mengirim email memerlukan alamat email. Untuk memberikan langkah-langkah informasi yang diperlukan ini, tentukan variabel input. Setelah ditentukan, variabel input biasanya ditetapkan oleh pengguna di kartu konfigurasi langkah saat pengguna menyiapkan langkah.

Tentukan variabel input di dua tempat: file manifes add-on, dan dalam kode dengan kartu konfigurasi tempat pengguna dapat memasukkan nilai untuk variabel input.

Menentukan variabel input dalam file manifes

Dalam file manifes, tentukan variabel input dengan array inputs[]. Setiap item dalam array inputs[] memiliki properti berikut:

  • id: ID unik untuk variabel input. Agar alur dapat mengaitkan elemen input kartu konfigurasi dengan variabel input ini, harus cocok dengan nama elemen kartu yang sesuai.
  • description: Deskripsi variabel input yang akan ditampilkan kepada pengguna akhir.
  • cardinality: Jumlah nilai yang diizinkan. Nilai yang mungkin adalah:
    • SINGLE: Hanya satu nilai yang diizinkan.
  • dataType: Jenis nilai yang diterima. dataType memiliki properti basicType yang menentukan jenis data. Nilai yang valid mencakup:
    • STRING: String alfanumerik.
    • INTEGER: Angka.
    • TIMESTAMP: Stempel waktu dalam format ISO 8601. Misalnya, dalam ISO 8601, 15 Maret 2025 ditampilkan sebagai 2025-03-15.
    • BOOLEAN: Benar atau salah.
    • EMAIL_ADDRESS: Alamat email dalam format dana@example.com.

Contoh berikut menentukan tiga variabel input untuk langkah kalkulator. Dua variabel input pertama adalah bilangan bulat, dan yang ketiga adalah operasi aritmetika.

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

Menentukan variabel input dalam kode

Kode langkah ini mencakup fungsi bernama onConfigFunction() yang menampilkan kartu konfigurasi yang menentukan satu widget kartu input untuk setiap variabel input yang ditentukan dalam array inputs[] file manifes.

Widget input yang ditentukan dalam kartu konfigurasi memiliki persyaratan berikut:

  • name setiap widget input harus cocok dengan id variabel input yang sesuai dalam file manifes.
  • Kardinalitas widget input harus cocok dengan cardinality variabel input dalam file manifes.
  • Jenis data widget input harus cocok dengan dataType variabel input dalam file manifes. Jika variabel input memiliki dataType bilangan bulat, variabel tersebut tidak dapat menyimpan string.

Untuk mendapatkan bantuan dalam membuat antarmuka kartu, lihat salah satu opsi berikut:

  • Pembuat Kartu: Alat interaktif yang dapat Anda gunakan untuk membuat dan menentukan kartu.
  • Kartu: dalam dokumentasi referensi API add-on Google Workspace.
  • Card Service: Layanan Apps Script yang memungkinkan skrip mengonfigurasi dan membuat kartu.
  • Ringkasan antarmuka berbasis Kartu: di dokumentasi developer add-on Google Workspace.

Contoh berikut menampilkan kartu konfigurasi untuk setiap widget input yang ditentukan dalam Tentukan variabel input dalam file manifes.

Apps Script

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

Memvalidasi variabel input

Sebagai praktik terbaik, validasi bahwa pengguna memasukkan nilai yang sesuai. Lihat Memvalidasi variabel input.