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 "milidetik sejak epoch Unix". Misalnya, 27 November 2025, 16.49.02 UTC ditampilkan sebagai 1764262142988.
- 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": "calculatorDemo",
          "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 di 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 input fields are configured to let the user select outputs from previous
* workflow steps as input values using the `hostAppDataSource` property.
*/
function onConfigCalculate() {
  const firstInput = CardService.newTextInput()
    .setFieldName("value1") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setTitle("First Value")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );

  const secondInput = CardService.newTextInput()
    .setFieldName("value2") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setTitle("Second Value")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    );

  const selectionInput = CardService.newSelectionInput()
    .setTitle("operation")
    .setFieldName("operation") // "FieldName" must match an "id" in the manifest file's inputs[] array.
    .setType(CardService.SelectionInputType.DROPDOWN)
    .addItem("+", "+", false)
    .addItem("-", "-", true)
    .addItem("x", "x", false)
    .addItem("/", "/", false);

  const sections = CardService.newCardSection()
    .setHeader("Action_sample: Calculate")
    .setId("section_1")
    .addWidget(firstInput)
    .addWidget(selectionInput)
    .addWidget(secondInput)

  let card = CardService.newCardBuilder()
    .addSection(sections)
    .build();

  return card;
}

Menggunakan variabel output dari langkah sebelumnya

Anda dapat mengonfigurasi variabel input untuk menerima variabel output dari langkah-langkah sebelumnya dalam alur kerja.

Mengaktifkan pemilihan variabel

Untuk mengizinkan pengguna memilih variabel dari langkah sebelumnya, gunakan properti includeVariables di widget TextInput dan SelectionInput.

Widget TextInput dan SelectionInput memiliki fitur khusus Workspace Studio berikut:

includeVariables: Properti boolean yang memungkinkan pengguna memilih variabel dari langkah sebelumnya. Agar pemilih variabel ditampilkan pada langkah-langkah selanjutnya, peristiwa awal dan setidaknya satu variabel output yang sesuai harus dipetakan ke variabel.
type: Nilai yang di-enum yang melengkapi otomatis saran. Nilai yang didukung meliputi:
- USER: Memberikan saran pelengkapan otomatis untuk orang-orang dalam kontak pengguna.
- SPACE: Memberikan saran pelengkapan otomatis untuk ruang Google Chat tempat pengguna menjadi anggotanya.

Jika includeVariables dan type ditetapkan, kolom input akan menggabungkan pengalaman mereka. Pengguna dapat memilih variabel type yang cocok dari menu drop-down, dan melihat saran pelengkapan otomatis untuk variabel tersebut.

Gambar 4: Pengguna meninjau saran pelengkapan otomatis saat memilih ruang.
Gambar 5: Pengguna memilih variabel output dari langkah sebelumnya dari drop-down ➕Variabel.

Memilih hanya satu variabel output dengan menu tambahan

Anda dapat mengonfigurasi widget SelectionInput untuk memungkinkan pengguna memilih satu variabel output dari langkah sebelumnya menggunakan menu tambahan.

Saat Anda menyetel SelectionInputType ke OVERFLOW_MENU, widget berfungsi sebagai pemilih variabel khusus. Tidak seperti penggunaan includeVariables dengan TextInput, yang mengonversi nilai variabel menjadi string, OVERFLOW_MENU mempertahankan jenis data asli dari variabel yang dipilih.

Apps Script

const selectionInput = CardService.newSelectionInput()
  .setFieldName("variable_picker_1")
  .setTitle("Variable Picker")
  .setType(
    CardService.SelectionInputType.OVERFLOW_MENU
  );

Mengizinkan pengguna menggabungkan teks dan variabel output

Anda dapat mengonfigurasi widget TextInput untuk mengontrol cara pengguna berinteraksi dengan teks dan variabel output menggunakan setInputMode().

RICH_TEXT: Memungkinkan pengguna menggabungkan teks dan variabel output. Hasilnya adalah satu string yang digabungkan.
PLAIN_TEXT: Membatasi input. Pengguna dapat mengetik teks atau memilih satu variabel output. Memilih variabel akan menggantikan teks yang ada. Gunakan mode ini untuk menerapkan jenis data tertentu yang ditentukan dalam manifes.

Gambar berikut menampilkan dua widget TextInput. Yang pertama dikonfigurasi sebagai RICH_TEXT dan menampilkan teks serta variabel output. Yang kedua dikonfigurasi sebagai PLAIN_TEXT dan hanya mengizinkan variabel output.

Gambar 3: Widget input teks yang dikonfigurasi sebagai RICH_TEXT dan PLAIN_TEXT.

Sebaiknya Anda menetapkan mode input secara eksplisit untuk semua widget TextInput.

Berikut adalah file manifes untuk mengonfigurasi widget TextInput dengan mode input yang berbeda:

JSON

{
  "timeZone": "America/Toronto",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Text and output variable demo",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "richTextDemo",
          "state": "ACTIVE",
          "name": "Rich Text Demo",
          "description": "Show the difference between rich text and plain text TextInput widgets",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "First user input",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              },
              {
                "id": "value2",
                "description": "Second user input",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfiguration",
            "onExecuteFunction": "onExecution"
          }
        }
      ]
    }
  }
}

Berikut kode untuk mengonfigurasi widget TextInput dengan berbagai mode input:

Apps Script

function onConfiguration() {
  const input1 = CardService.newTextInput()
    .setFieldName("value1")
    .setId("value1")
    .setTitle("Rich Text")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    )
    // Set input mode to RICH_TEXT to allow mixed text and variables.
    .setInputMode(CardService.TextInputMode.RICH_TEXT);

  const input2 = CardService.newTextInput()
    .setFieldName("value2")
    .setId("value2")
    .setTitle("Plain text")
    .setHostAppDataSource(
      CardService.newHostAppDataSource()
        .setWorkflowDataSource(
          CardService.newWorkflowDataSource()
            .setIncludeVariables(true)
        )
    )
    // Set input mode to PLAIN_TEXT to enforce single variable selection.
    .setInputMode(CardService.TextInputMode.PLAIN_TEXT);

  const section = CardService.newCardSection()
    .addWidget(input1)
    .addWidget(input2);

  const card = CardService.newCardBuilder()
    .addSection(section)
    .build();

  return card;
}

function onExecution(e) {
}

Menyesuaikan tombol pemilih variabel

Anda dapat menyesuaikan tombol pemilih variabel dengan menyetel ukuran dan label tombol.

Ukuran tombol

Untuk menyetel ukuran tombol, gunakan setVariableButtonSize() dengan salah satu enum VariableButtonSize berikut:

UNSPECIFIED: Default. Tombol ini ringkas di panel samping dan berukuran penuh dalam konteks lain.
COMPACT: Tombol hanya menampilkan tanda plus (+).
FULL_SIZE: Tombol menampilkan label teks lengkap.

Label tombol

Untuk menetapkan teks tombol, gunakan setVariableButtonLabel().

Contoh: Penyesuaian pemilih variabel

Contoh berikut menunjukkan cara mengonfigurasi widget TextInput dengan berbagai ukuran tombol pemilih variabel dan label kustom.

Gambar 1: Penyesuaian tombol pemilih variabel di web.
Gambar 2: Penyesuaian tombol pemilih variabel di panel samping add-on.

Berikut adalah file manifes untuk menyesuaikan tombol pemilih variabel:

JSON

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.locale"
  ],
  "addOns": {
    "common": {
      "name": "Variable button customization",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "variable_picker_customization",
          "state": "ACTIVE",
          "name": "Variable Picker demo",
          "description": "List all possible variable picker customization options",
          "workflowAction": {
            "onConfigFunction": "onUpdateCardConfigFunction",
            "onExecuteFunction": "onUpdateCardExecuteFunction"
          }
        }
      ]
    }
  }
}

Berikut kode untuk menyesuaikan tombol pemilih variabel:

Apps Script

function onUpdateCardConfigFunction(event) {
  const textInput1 = CardService.newTextInput()
    .setFieldName("value1")
    .setTitle("Regular variable picker button")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonSize(CardService.VariableButtonSize.UNSPECIFIED)
      )
    );

  const textInput2 = CardService.newTextInput()
    .setFieldName("value2")
    .setTitle("Size: Unspecified")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonSize(CardService.VariableButtonSize.UNSPECIFIED)
      )
    );

  const textInput3 = CardService.newTextInput()
    .setFieldName("value3")
    .setTitle("Size: Full size")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonSize(CardService.VariableButtonSize.FULL_SIZE)
      )
    );

  const textInput4 = CardService.newTextInput()
    .setFieldName("value4")
    .setTitle("Size: Compact")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonSize(CardService.VariableButtonSize.COMPACT)
      )
    );

  const textInput5 = CardService.newTextInput()
    .setFieldName("value5")
    .setTitle("Custom button label")
    .setHostAppDataSource(
      CardService.newHostAppDataSource().setWorkflowDataSource(
        CardService.newWorkflowDataSource()
          .setIncludeVariables(true)
          .setVariableButtonLabel("New button label!")
      )
    );

  var cardSection = CardService.newCardSection()
    .addWidget(textInput1)
    .addWidget(textInput2)
    .addWidget(textInput3)
    .addWidget(textInput4)
    .addWidget(textInput5)
    .setId("section_1");

  var card = CardService.newCardBuilder().addSection(cardSection).build();

  return card;
}

function onUpdateCardExecuteFunction(event) {
}

Mengonfigurasi perlengkapan otomatis data Google Workspace

Anda juga dapat mengisi saran pelengkapan otomatis dari data dalam lingkungan Google Workspace pengguna:

Pengguna Google Workspace: Mengisi pengguna dalam organisasi Google Workspace yang sama.
Ruang Google Chat: Mengisi ruang Google Chat tempat pengguna menjadi anggota.

Untuk mengonfigurasi ini, tetapkan PlatformDataSource di widget SelectionInput, dengan menentukan WorkflowDataSourceType sebagai USER atau SPACE.

Apps Script

// User Autocomplete
var multiSelect2 =
  CardService.newSelectionInput()
    .setFieldName("value2")
    .setTitle("User Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.USER)
            ))
    );

// Chat Space Autocomplete
var multiSelect3 =
  CardService.newSelectionInput()
    .setFieldName("value3")
    .setTitle("Chat Space Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            ))
    );

Contoh: Menggabungkan jenis pelengkapan otomatis

Contoh berikut menunjukkan fungsi onConfig yang membuat kartu dengan tiga widget SelectionInput, yang menunjukkan pelengkapan otomatis sisi server, pengguna, dan ruang:

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Autocomplete Demo",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "autocomplete_demo",
          "state": "ACTIVE",
          "name": "Autocomplete Demo",
          "description": "Provide autocompletion in input fields",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "A multi-select field with autocompletion",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigAutocomplete",
            "onExecuteFunction": "onExecuteAutocomplete"
          }
        }
      ]
    }
  }
}

Apps Script

function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // Server-side autocomplete widget
  var multiSelect1 =
    CardService.newSelectionInput()
      .setFieldName("value1")
      .setTitle("Server Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .addDataSourceConfig(
        CardService.newDataSourceConfig()
          .setRemoteDataSource(
            CardService.newAction().setFunctionName('getAutocompleteResults')
          )
      )
      .addDataSourceConfig(
        CardService.newDataSourceConfig()
          .setPlatformDataSource(
            CardService.newPlatformDataSource()
              .setHostAppDataSource(
                CardService.newHostAppDataSource()
                  .setWorkflowDataSource(
                    CardService.newWorkflowDataSource()
                      .setIncludeVariables(true)
                  ))
          )
      );

  // User autocomplete widget
  var multiSelect2 =
    CardService.newSelectionInput()
      .setFieldName("value2")
      .setTitle("User Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.USER)
              ))
      );

  // Space autocomplete widget
  var multiSelect3 =
    CardService.newSelectionInput()
      .setFieldName("value3")
      .setTitle("Chat Space Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.SPACE)
              ))
      );

  var sectionBuilder =
    CardService.newCardSection()
      .addWidget(multiSelect1)
      .addWidget(multiSelect2)
      .addWidget(multiSelect3);

  var card =
    CardService.newCardBuilder()
      .addSection(sectionBuilder)
      .build();
  return card;
}

function handleAutocompleteRequest(event) {
  var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
  var query = event.workflow.elementUiAutocomplete.query;

  if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
    return {};
  }

  // Query your data source to get results
  let autocompleteResponse = AddOnsResponseService.newUpdateWidget()
    .addSuggestion(
      query + " option 1",
      query + "_option1",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 1 bottom text"
    )
    .addSuggestion(
      query + " option 2",
      query + "_option2",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 2 bottom text"
    ).addSuggestion(
      query + " option 3",
      query + "_option3",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 3 bottom text"
    );

  const modifyAction = AddOnsResponseService.newAction()
    .addModifyCard(
      AddOnsResponseService.newModifyCard()
        .setUpdateWidget(autocompleteResponse)
    );

  return AddOnsResponseService.newRenderActionBuilder()
    .setAction(modifyAction)
    .build();
}

Memvalidasi variabel input

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

Mengumpulkan data dengan variabel input Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Menentukan variabel input dalam file manifes

JSON

Menentukan variabel input dalam kode

Apps Script

Menggunakan variabel output dari langkah sebelumnya

Mengaktifkan pemilihan variabel

Memilih hanya satu variabel output dengan menu tambahan

Apps Script

Mengizinkan pengguna menggabungkan teks dan variabel output

JSON

Apps Script

Menyesuaikan tombol pemilih variabel

Ukuran tombol

Label tombol

Contoh: Penyesuaian pemilih variabel

JSON

Apps Script

Mengonfigurasi perlengkapan otomatis data Google Workspace

Apps Script

Contoh: Menggabungkan jenis pelengkapan otomatis

JSON

Apps Script

Memvalidasi variabel input

Topik terkait

Mengumpulkan data dengan variabel input