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

Chương trình Gemini Alpha: Flows có trong chương trình Gemini Alpha.

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

Nhìn chung, để tạo một 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ẻ là 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.
• Card Service, 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ó chức năng và tính năng đặc biệt dành riêng cho Workspace Flows, đượ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": "Sample add-on",
      "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": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

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() {
  var card = {
    "sections": [
      {
        "header": "Choose a Chat space",
        "widgets": [
          {
            "selectionInput": {
              "name": "value1",
              "label": "First value",
              "type": "MULTI_SELECT",
              "platformDataSource": {
                "hostAppDataSource": {
                  "workflowDataSource": {
                    "includeVariables": true,
                    "type": "SPACE"
                  }
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

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 một DataSourceConfig chỉ định một 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
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

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

Tính năng tự động hoàn thành dữ liệu trong Google Workspace

Bạn cũng có thể điền sẵn các đề xuất tự động hoàn thành từ dữ liệu trong môi trường Google Workspace của người dùng:

• Người dùng Google Workspace: Điền sẵn thông tin người dùng trong cùng một tổ chức Google Workspace.
• Không gian trong Google Chat: Điền sẵn các không gian trong Google Chat mà người dùng là thành viên.

Để định cấu hình chế độ này, hãy đặt PlatformDataSource trong tiện ích SelectionInput, chỉ định WorkflowDataSourceType là USER hoặc 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)
            ))
    );

Ví dụ: Kết hợp các loại tính năng tự động hoàn thành

Ví dụ sau đây cho thấy một hàm onConfig tạo thẻ có 3 tiện ích SelectionInput, minh hoạ tính năng tự động hoàn thành phía máy chủ, người dùng và không gian:

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
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

Các tính năng dành riêng cho Workspace Flows

Một số tiện ích thẻ có các chức năng và tính năng đặc biệt dành riêng cho Workspace Flows, được mô tả chi tiết tại đây.

TextInput và SelectionInput

Tiện ích TextInput và SelectionInput có các tính năng dành riêng cho Workspace Flows sau đây:

• includeVariables: Một thuộc tính boolean cho phép người dùng chọn các biến từ các bước trước.
• type: Một giá trị được liệt kê tự động hoàn thành các đề xuất. Sau đây là các giá trị được hỗ trợ:
  • USER: Đưa ra đề xuất tự động hoàn thành cho những người trong danh bạ của người dùng.
  • SPACE: Đưa ra các đề xuất tự động hoàn thành cho những không gian trên Google Chat mà người dùng là thành viên.

Khi cả includeVariables và type đều được đặt, trường nhập sẽ kết hợp các trải nghiệm của chúng. Người dùng có thể chọn một biến số của type trùng khớp trong trình đơn thả xuống và xem các đề xuất tự động hoàn thành cho biến số đó.

• 

  Hình 1: Người dùng xem xét các đề xuất tự động hoàn thành khi chọn một không gian.

• 

  Hình 2: Người dùng chọn biến đầu ra của một bước trước đó trong trình đơn thả xuống ➕Biến.

Những điểm cần cân nhắc và hạn chế đối với thẻ

• Thao tác điều hướng bằng thẻ như popCard(), pushCard() và updateCard() không được hỗ trợ trong các tiện ích bổ sung mở rộng Luồng.

• Khi SelectionInput được dùng trong bộ chọn biến, các tiện ích chỉ hỗ trợ "type": "MULTI_SELECT". Ở những nơi khác trong thẻ cấu hình, SelectionInput hỗ trợ tất cả các giá trị của SelectionType.

Chủ đề có liên quan

• Tạo một bước
• Biến đầu vào
• Xác thực biến đầu vào
• Biến đầu ra
• Ghi nhật ký hoạt động và lỗi
• Đối tượng sự kiện Flows