Tworzenie karty konfiguracji dla kroku

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

Ogólnie rzecz biorąc, aby utworzyć kartę konfiguracji, musisz utworzyć interfejs karty, tak jak w przypadku każdego innego dodatku do Google Workspace. Aby uzyskać pomoc w tworzeniu interfejsów kart konfiguracji, zapoznaj się z tymi materiałami:

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

Niektóre widżety kart mają specjalne funkcje i możliwości dostępne w 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 w 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"
          }
        }
      ]
    }
  }
}

Edytuj kod

W kodzie aplikacji zwróć kartę.

Google 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 w przypadku widżetów wprowadzania

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

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

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

Autouzupełnianie po stronie serwera

Możesz skonfigurować widżet SelectionInput, aby autouzupełniał sugestie z zewnętrznego źródła danych. Możesz na przykład pomóc użytkownikom w wybraniu potencjalnych klientów z listy w systemie zarządzania relacjami z klientami (CRM).

Aby wdrożyć autouzupełnianie po stronie serwera, musisz:

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

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

Google 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 żądania autouzupełniania

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

  1. Sprawdź wartość parametru event.workflow.elementUiAutocomplete.invokedFunction, aby upewnić się, że jest zgodna z oczekiwaną nazwą funkcji.
  2. Pobierz dane wejściowe użytkownika z event.workflow.elementUiAutocomplete.query.
  3. Wysyłaj zapytania do zewnętrznego źródła danych za pomocą zapytania.
  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:

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

Uwagi i ograniczenia dotyczące kart