Membuat kartu konfigurasi untuk langkah

Panduan ini menjelaskan cara membuat kartu konfigurasi yang memungkinkan pengguna menyesuaikan dan memberikan input untuk langkah-langkah di Google Workspace Studio.

Secara umum, untuk membuat kartu konfigurasi, Anda membuat antarmuka kartu seperti yang Anda lakukan untuk add-on Google Workspace lainnya. Untuk mendapatkan bantuan dalam membuat antarmuka kartu konfigurasi, lihat artikel berikut:

  • Card Builder, alat interaktif yang membantu Anda 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.
  • Antarmuka berbasis kartu dalam dokumentasi developer add-on Google Workspace.

Beberapa widget kartu memiliki fungsi dan fitur khusus Workspace Studio, yang dijelaskan dalam panduan ini.

Menentukan kartu konfigurasi

Tentukan kartu konfigurasi dalam manifes Apps Script dan dalam kode.

Contoh berikut menunjukkan cara membuat kartu konfigurasi yang meminta pengguna memilih ruang Google Chat.

Mengedit file manifes

Dalam file manifes, tentukan workflowElements.

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Chat space selector",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/gsuite_addons/v6/web-24dp/logo_gsuite_addons_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Chat space selector",
          "description": "Lets the user select a space from Google  Chat",
          "workflowAction": {
            "inputs": [
              {
                "id": "chooseSpace",
                "description": "Choose a Chat space",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigSpacePicker",
            "onExecuteFunction": "onExecuteSpacePicker"
          }
        }
      ]
    }
  }
}

Edit kode

Dalam kode aplikasi, kembalikan kartu.

Apps Script

/**
 * Generates and displays a configuration card to choose a Chat space
 */
function onConfigSpacePicker() {

  const selectionInput = CardService.newSelectionInput()
    .setTitle("First Value")
    .setFieldName("chooseSpace")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            )
        )
    );

  const cardSection = CardService.newCardSection()
    .setHeader("Select Chat Space")
    .setId("section_1")
    .addWidget(selectionInput)

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

  return card;
}

function onExecuteSpacePicker(e) {
}

Menyiapkan pelengkapan otomatis untuk widget input

Anda dapat mengonfigurasi pelengkapan otomatis untuk widget SelectionInput guna membantu pengguna memilih dari daftar opsi. Misalnya, jika pengguna mulai mengetik Atl untuk menu yang mengisi kota-kota di Amerika Serikat, elemen Anda dapat menyarankan Atlanta secara otomatis sebelum pengguna selesai mengetik. Anda dapat melengkapi otomatis hingga 100 item.

Saran pelengkapan otomatis dapat berasal dari sumber data berikut:

  • Penyelesaian otomatis sisi server: Saran diisi dari sumber data pihak ketiga atau eksternal yang Anda tentukan.
  • Data Google Workspace: Saran diisi dari sumber Google Workspace, seperti pengguna Google Workspace atau ruang Google Chat.

Pelengkapan otomatis sisi server

Anda dapat mengonfigurasi widget SelectionInput untuk melengkapi otomatis saran dari sumber data eksternal. Misalnya, Anda dapat membantu pengguna memilih dari daftar prospek penjualan dari sistem pengelolaan hubungan pelanggan (CRM).

Untuk menerapkan pelengkapan otomatis sisi server, Anda harus:

  1. Tentukan sumber data: Di widget SelectionInput, tambahkan DataSourceConfig yang menentukan RemoteDataSource. Konfigurasi ini mengarah ke fungsi Apps Script yang mengambil saran pelengkapan otomatis.
  2. Terapkan fungsi pelengkapan otomatis: Fungsi ini dipicu saat pengguna mengetik di kolom input. Fungsi ini harus mengkueri sumber data eksternal Anda berdasarkan input pengguna dan menampilkan daftar saran.

Contoh berikut menunjukkan cara mengonfigurasi widget SelectionInput untuk pelengkapan otomatis di sisi server:

Apps Script

// In your onConfig function:
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)
                ))
        )
    );

// ... add widget to card ...

Menangani permintaan pelengkapan otomatis

Fungsi yang ditentukan di setFunctionName (misalnya, getAutocompleteResults) menerima objek peristiwa saat pengguna mengetik di kolom. Fungsi ini harus:

  1. Periksa event.workflow.elementUiAutocomplete.invokedFunction untuk memastikan nama fungsi cocok dengan yang diharapkan.
  2. Dapatkan input pengguna dari event.workflow.elementUiAutocomplete.query.
  3. Buat kueri sumber data eksternal menggunakan kueri.
  4. Menampilkan hingga 100 saran dalam format yang diperlukan.

Contoh berikut menunjukkan cara menerapkan fungsi handleAutocompleteRequest() untuk menampilkan saran berdasarkan kueri pengguna:

Apps Script

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 based on the query
  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();
}

// In your onConfig function, handle the autocomplete event
function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // ... rest of your card building logic ...
}

Pertimbangan dan batasan kartu