Tạo thẻ cấu hình cho một bước

Hướng dẫn này giải thích cách tạo một thẻ cấu hình cho phép người dùng tuỳ chỉnh và cung cấp thông tin đầu vào cho một bước trong Google Workspace Studio.

Nhìn chung, để tạo thẻ cấu hình, bạn sẽ tạo một giao diện thẻ giống như khi tạo bất kỳ tiện ích bổ sung nào khác của Google Workspace. Để được trợ giúp về cách tạo giao diện thẻ cấu hình, hãy xem các mục sau:

  • Trình tạo thẻ, một công cụ tương tác giúp bạn tạo và xác định thẻ.
  • Thẻ trong tài liệu tham khảo về API tiện ích bổ sung của Google Workspace.
  • Dịch vụ thẻ, một dịch vụ Apps Script cho phép tập lệnh định cấu hình và tạo thẻ.
  • Giao diện dựa trên thẻ trong tài liệu dành cho nhà phát triển tiện ích bổ sung của Google Workspace.

Một số tiện ích thẻ có các tính năng và chức năng đặc biệt dành riêng cho Workspace Studio, được trình bày chi tiết trong hướng dẫn này.

Xác định thẻ cấu hình

Xác định thẻ cấu hình trong cả tệp kê khai Apps Script và trong mã.

Ví dụ sau đây cho thấy cách tạo một thẻ cấu hình yêu cầu người dùng chọn một không gian trên Google Chat.

Chỉnh sửa tệp kê khai

Trong tệp kê khai, hãy xác định 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"
          }
        }
      ]
    }
  }
}

Chỉnh sửa đoạn mã

Trong mã ứng dụng, hãy trả về một thẻ.

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) {
}

Thiết lập tính năng tự động hoàn thành cho các tiện ích đầu vào

Bạn có thể thiết lập tính năng tự động hoàn tất cho các tiện ích SelectionInput để giúp người dùng chọn trong danh sách các lựa chọn. Ví dụ: nếu người dùng bắt đầu nhập Atl cho một trình đơn điền sẵn các thành phố ở Hoa Kỳ, thì phần tử của bạn có thể tự động đề xuất Atlanta trước khi người dùng nhập xong. Bạn có thể tự động hoàn tất tối đa 100 mục.

Đề xuất tự động hoàn thành có thể đến từ các nguồn dữ liệu sau:

  • Tính năng tự động hoàn thành phía máy chủ: Các đề xuất được điền sẵn từ một nguồn dữ liệu bên ngoài hoặc bên thứ ba do bạn xác định.
  • Dữ liệu trên Google Workspace: Các đề xuất được lấy từ các nguồn trên Google Workspace, chẳng hạn như người dùng Google Workspace hoặc không gian trên Google Chat.

Tính năng tự động hoàn thành phía máy chủ

Bạn có thể định cấu hình một tiện ích SelectionInput để tự động hoàn thành các đề xuất từ một nguồn dữ liệu bên ngoài. Ví dụ: bạn có thể giúp người dùng chọn trong danh sách khách hàng tiềm năng từ hệ thống quản lý quan hệ khách hàng (CRM).

Để triển khai tính năng tự động hoàn thành phía máy chủ, bạn cần:

  1. Xác định nguồn dữ liệu: Trong tiện ích SelectionInput, hãy thêm DataSourceConfig chỉ định RemoteDataSource. Cấu hình này trỏ đến một hàm Apps Script tìm nạp các đề xuất tự động hoàn thành.
  2. Triển khai hàm tự động hoàn thành: Hàm này được kích hoạt khi người dùng nhập vào trường nhập. Hàm này sẽ truy vấn nguồn dữ liệu bên ngoài dựa trên dữ liệu đầu vào của người dùng và trả về danh sách các đề xuất.

Ví dụ sau đây cho thấy cách định cấu hình tiện ích SelectionInput cho tính năng tự động hoàn thành phía máy chủ:

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 ...

Xử lý yêu cầu tự động hoàn thành

Hàm được chỉ định trong setFunctionName (ví dụ: getAutocompleteResults) sẽ nhận được một đối tượng sự kiện khi người dùng nhập vào trường. Hàm này phải:

  1. Kiểm tra event.workflow.elementUiAutocomplete.invokedFunction để đảm bảo tên này khớp với tên hàm dự kiến.
  2. Lấy thông tin đầu vào của người dùng từ event.workflow.elementUiAutocomplete.query.
  3. Truy vấn nguồn dữ liệu bên ngoài bằng truy vấn.
  4. Trả về tối đa 100 đề xuất theo định dạng bắt buộc.

Ví dụ sau đây cho thấy cách triển khai hàm handleAutocompleteRequest() để trả về các đề xuất dựa trên truy vấn của người dùng:

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 ...
}

Những điểm cần lưu ý và hạn chế đối với thẻ