Tworzenie karty konfiguracji dla kroku

Z tego przewodnika dowiesz się, jak utworzyć kartę konfiguracji, która umożliwia użytkownikom dostosowywanie i wprowadzanie danych do kroku w Google Workspace Studio.

Aby utworzyć kartę konfiguracji, musisz utworzyć interfejs karty, tak jak w przypadku każdego innego dodatku do Google Workspace. Więcej informacji o tworzeniu interfejsów kart konfiguracji znajdziesz w tych materiałach:

  • Kreator kart – interaktywne narzędzie, które pomaga tworzyć i definiować karty.
  • Karta w dokumentacji API Google Workspace Add-ons.
  • Usługa kart – usługa Apps Script, która umożliwia skryptom konfigurowanie i tworzenie kart.
  • Interfejsy oparte na kartach w dokumentacji dla deweloperów dodatków do Google Workspace.

Niektóre widżety kart mają specjalne funkcje i cechy Workspace Studio, które zostały opisane w tym przewodniku.

Definiowanie karty konfiguracji

Zdefiniuj kartę konfiguracji w pliku manifestu Apps Script i w kodzie.

Poniższy przykład pokazuje, jak utworzyć kartę konfiguracji, która prosi użytkowników o wybranie pokoju Google Chat.

Edytowanie pliku manifestu

W pliku manifestu zdefiniuj 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"
          }
        }
      ]
    }
  }
}

Edytowanie kodu

W kodzie aplikacji zwróć kartę.

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

Konfigurowanie autouzupełniania widżetów wejściowych

Możesz skonfigurować autouzupełnianie widżetów SelectionInput aby ułatwić użytkownikom wybieranie z listy opcji. Jeśli na przykład użytkownik zacznie wpisywać Atl w menu, które zawiera miasta w Stanach Zjednoczonych, Twój element może automatycznie zasugerować Atlanta, zanim użytkownik skończy wpisywać. Możesz automatycznie uzupełnić maksymalnie 100 elementów.

Sugestie autouzupełniania mogą pochodzić z tych źródeł danych:

  • Autouzupełnianie po stronie serwera: sugestie są wypełniane na podstawie źródła danych innej firmy lub zewnętrznego źródła danych, które zdefiniujesz.
  • Dane Google Workspace: sugestie są wypełniane na podstawie źródeł Google Workspace, takich jak użytkownicy Google Workspace lub pokoje Google Chat.

Autouzupełnianie po stronie serwera

Możesz skonfigurować widżet SelectionInput aby automatycznie uzupełniać sugestie na podstawie zewnętrznego źródła danych. Możesz na przykład ułatwić użytkownikom wybieranie z listy potencjalnych klientów z systemu zarządzania relacjami z klientami (CRM).

Aby zaimplementować autouzupełnianie po stronie serwera:

  1. Zdefiniuj źródło danych: w SelectionInput widżecie dodaj DataSourceConfig, który określa RemoteDataSource. Ta konfiguracja wskazuje funkcję Apps Script, która pobiera sugestie autouzupełniania.
  2. Zaimplementuj funkcję autouzupełniania: ta funkcja jest wywoływana, gdy użytkownik wpisuje tekst w polu do wprowadzania danych. Funkcja powinna wysyłać zapytania do zewnętrznego źródła danych na podstawie danych wprowadzonych przez użytkownika i zwracać listę sugestii.

Poniższy przykład pokazuje, jak skonfigurować SelectionInput widżet do autouzupełniania po stronie serwera:

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

Obsługa prośby o autouzupełnianie

Gdy użytkownik wpisuje tekst w polu, funkcja określona w setFunctionName (np. getAutocompleteResults) otrzymuje obiekt zdarzenia. Ta funkcja musi:

  1. Sprawdź event.workflow.elementUiAutocomplete.invokedFunction, aby upewnić się, że pasuje do oczekiwanej nazwy funkcji.
  2. Pobierz dane wpisane przez użytkownika z event.workflow.elementUiAutocomplete.query.
  3. Wyślij zapytanie do zewnętrznego źródła danych.
  4. Zwróć maksymalnie 100 sugestii w wymaganym formacie.

Poniższy przykład pokazuje, jak zaimplementować funkcję handleAutocompleteRequest, aby zwracać sugestie na podstawie zapytania użytkownika:

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

Względy i ograniczenia dotyczące kart