Ta strona została przetłumaczona przez Cloud Translation API.

Tworzenie karty konfiguracji dla kroku

Z tego przewodnika dowiesz się, jak utworzyć kartę konfiguracji, która umożliwia użytkownikom dostosowywanie i podawanie danych wejściowych dla 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 widżetów SelectionInput, aby ułatwić użytkownikom wybieranie opcji z listy. Jeśli na przykład użytkownik zacznie wpisywać Atl w przypadku menu, które zawiera miasta 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:

Zdefiniuj źródło danych: w widżecie SelectionInput dodaj DataSourceConfig, który określa RemoteDataSource. Ta konfiguracja wskazuje funkcję Apps Script, która pobiera sugestie autouzupełniania.
Wdróż funkcję autouzupełniania: ta funkcja jest wywoływana, gdy użytkownik wpisuje tekst w polu wejściowym. Funkcja powinna wysyłać zapytanie 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 polu setFunctionName (np. getAutocompleteResults) otrzymuje obiekt zdarzenia, gdy użytkownik wpisuje tekst w polu. Ta funkcja musi:

Sprawdź wartość parametru event.workflow.elementUiAutocomplete.invokedFunction, aby upewnić się, że jest zgodna z oczekiwaną nazwą funkcji.
Pobierz dane wejściowe użytkownika z event.workflow.elementUiAutocomplete.query.
Wyślij zapytanie do zewnętrznego źródła danych.
Zwróć maksymalnie 100 sugestii w wymaganym formacie.

Poniższy przykład pokazuje, jak wdrożyć 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 ...
}

Autouzupełnianie danych Google Workspace

Możesz też wypełniać sugestie autouzupełniania danymi z środowiska Google Workspace użytkownika:

Użytkownicy Google Workspace: wypełnij listę użytkowników w tej samej organizacji Google Workspace.
Pokoje Google Chat: wypełniaj pokoje Google Chat, których użytkownik jest członkiem.

Aby to skonfigurować, ustaw wartość PlatformDataSource w widżecie SelectionInput, określając WorkflowDataSourceType jako USER lub SPACE.

Google 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)
            ))
    );

Przykład: łączenie typów autouzupełniania

Przykład poniżej pokazuje funkcję onConfig, która tworzy kartę z 3 widgetami SelectionInput. Demonstruje ona autouzupełnianie po stronie serwera, użytkownika i przestrzeni:

JSON

json { "timeZone": "America/Los_Angeles", "exceptionLogging": "STACKDRIVER", "runtimeVersion": "V8", "addOns": { "common": { "name": "Autocomplete Demo", "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png", "useLocaleFromApp": true }, "flows": { "workflowElements": [ { "id": "autocomplete_demo", "state": "ACTIVE", "name": "Autocomplete Demo", "description": "Provide autocompletion in input fields", "workflowAction": { "inputs": [ { "id": "value1", "description": "A multi-select field with autocompletion", "cardinality": "SINGLE", "dataType": { "basicType": "STRING" } } ], "onConfigFunction": "onConfigAutocomplete", "onExecuteFunction": "onExecuteAutocomplete" } } ] } } }

Google 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
  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();
}

Funkcje specyficzne dla Workspace Studio

Niektóre widżety kart mają specjalne funkcje i możliwości Workspace Studio, które zostały opisane tutaj.

TextInput i SelectionInput

Widżety TextInput i SelectionInput mają te funkcje Workspace Studio:

includeVariables: właściwość logiczna, która umożliwia użytkownikom wybieranie zmiennych z poprzednich kroków. Aby w późniejszych krokach wyświetlić selektor zmiennych, zarówno zdarzenie początkowe, jak i co najmniej 1 odpowiadająca mu zmienna wyjściowa muszą być mapowane na zmienną.
type: wartość wyliczeniowa, która automatycznie uzupełnia sugestie. Obsługiwane wartości to:
- USER: podaje sugestie autouzupełniania dotyczące osób z kontaktów użytkownika.
- SPACE: podaje sugestie autouzupełniania dotyczące pokoi w Google Chat, do których należy użytkownik.

Jeśli ustawisz zarówno includeVariables, jak i type, pole wejściowe połączy ich funkcje. Użytkownicy mogą wybrać zmienną pasującego type z menu i wyświetlić sugestie autouzupełniania.

Ilustracja 1. Użytkownik sprawdza sugestie autouzupełniania podczas wybierania miejsca.
Ilustracja 2. Użytkownik wybiera zmienną wyjściową z poprzedniego kroku z menu ➕Zmienne.

Uwagi i ograniczenia dotyczące kart

Nawigacja po kartach, np. popCard(),pushCard() i updateCard(), nie jest obsługiwana w dodatkach, które rozszerzają Agenty.
Gdy SelectionInput jest używany w selektorze zmiennych, widżety obsługują tylko "type": "MULTI_SELECT". W innych kartach konfiguracji SelectionInput obsługuje wszystkie wartości SelectionType.

Tworzenie karty konfiguracji dla kroku Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Definiowanie karty konfiguracji

Edytowanie pliku manifestu

JSON

Edytuj kod

Google Apps Script

Konfigurowanie autouzupełniania w przypadku widżetów wprowadzania

Autouzupełnianie po stronie serwera

Google Apps Script

Obsługa żądania autouzupełniania

Google Apps Script

Autouzupełnianie danych Google Workspace

Google Apps Script

Przykład: łączenie typów autouzupełniania

JSON

Google Apps Script

Funkcje specyficzne dla Workspace Studio

TextInput i SelectionInput

Uwagi i ograniczenia dotyczące kart

Powiązane artykuły

Tworzenie karty konfiguracji dla kroku