Zbieranie i przetwarzanie informacji od użytkowników Google Chat

Z tego przewodnika dowiesz się, jak aplikacje Google Chat mogą zbierać i przetwarzać informacje od użytkowników, tworząc dane wejściowe formularzy w interfejsach opartych na kartach.

Okno z różnymi widżetami.
Ilustracja 1. Przykładowa aplikacja Google Chat, która otwiera okno do zbierania informacji kontaktowych.

Aplikacje do Google Chat proszą użytkowników o informacje, aby wykonywać działania w Google Chat lub poza nim, m.in. w następujący sposób:

  • Skonfiguruj ustawienia. Możesz na przykład pozwolić użytkownikom na dostosowywanie ustawień powiadomień lub konfigurowanie i dodawanie aplikacji do Google Chat do co najmniej 1 pokoju.
  • tworzyć i aktualizować informacje w innych aplikacjach Google Workspace; Możesz na przykład pozwolić użytkownikom na tworzenie wydarzeń w Kalendarzu Google.
  • Zezwalaj użytkownikom na dostęp do zasobów w innych aplikacjach lub usługach internetowych i ich aktualizowanie. Na przykład aplikacja do Google Chat może pomóc użytkownikom zaktualizować stan zgłoszenia do zespołu pomocy bezpośrednio z pokoju Google Chat.

Wymagania wstępne

HTTP

aplikację Google Chat, która odbiera interakcje użytkowników i na nie odpowiada; Aby ją utworzyć, wykonaj czynności opisane w krótkim wprowadzeniu do HTTP.

Google Apps Script

aplikację Google Chat, która odbiera interakcje użytkowników i na nie odpowiada; Aby go utworzyć, wykonaj czynności opisane w krótkim wprowadzeniu do Apps Script.

Tworzenie formularzy za pomocą kart

Aby zbierać informacje, aplikacje do Google Chat projektują formularze i ich dane wejściowe oraz umieszczają je na kartach. Aby wyświetlać karty użytkownikom, aplikacje do Google Chat mogą używać tych interfejsów Google Chat:

  • Wiadomości zawierające co najmniej 1 kartę.
  • Strony główne, czyli karty wyświetlane na karcie Strona główna w czatach z aplikacją Google Chat.
  • okna, czyli karty, które otwierają się w nowym oknie z wiadomości i stron głównych;

Aplikacje do Google Chat mogą tworzyć karty za pomocą tych widżetów:

  • widżety do wprowadzania danych w formularzu, które proszą użytkowników o informacje; Opcjonalnie możesz dodać weryfikację do widżetów wprowadzania danych w formularzu, aby mieć pewność, że użytkownicy wprowadzają i formatują informacje prawidłowo. Aplikacje do Google Chat mogą używać tych widżetów do wprowadzania danych w formularzu:

    • Pola tekstowe (textInput) do wpisywania dowolnego tekstu lub wybierania sugerowanego tekstu.
    • Dane wejściowe wyboru (selectionInput) to elementy interfejsu, które można wybrać, takie jak pola wyboru, przyciski opcji i menu. Widżety wyboru mogą też wypełniać i sugerować elementy na podstawie danych Google Workspace (np. pokoju czatu) lub dynamicznego źródła danych. Szczegółowe informacje znajdziesz w sekcjach Dodawanie menu i Dodawanie menu wielokrotnego wyboru.
    • Selektory daty i godziny (dateTimePicker) do wprowadzania daty i godziny.

  • Widżet przycisku, aby użytkownicy mogli przesyłać wartości wpisane na karcie. Gdy użytkownik kliknie przycisk, aplikacja Google Chat może przetworzyć otrzymane informacje.

W tym przykładzie karta zbiera informacje kontaktowe za pomocą pola tekstowego, selektora daty i godziny oraz pola wyboru:

Więcej przykładów interaktywnych widżetów, których możesz używać do zbierania informacji, znajdziesz w artykule Projektowanie interaktywnej karty lub okna.

Dodawanie menu

Aby dostosować elementy wyboru lub umożliwić użytkownikom wybranie pojedynczego elementu z dynamicznego źródła danych, aplikacje do Google Chat mogą używać menu, które są rodzajem widżetu SelectionInput. Na przykład na tej karcie wyświetla się menu, w którym użytkownicy mogą dynamicznie wybierać kontakty z listy:

Elementy menu możesz wypełnić danymi z tych źródeł:

Wypełnianie elementów danymi ze źródła danych Google Workspace

Aby wypełnić elementy ze źródeł danych Google Workspace, takich jak użytkownicy Google Workspace, określ pole platformDataSource w obiekcie DataSourceConfig. W przeciwieństwie do innych typów danych wejściowych wyboru pomijasz obiekty SelectionItem, ponieważ te elementy wyboru są dynamicznie pobierane z Google Workspace.

Poniższy kod wyświetla menu użytkowników Google Workspace:

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "contacts",
            "type": "DROPDOWN",
            "label": "Select contact from organization",
            "dataSourceConfigs": [
              {
                "platformDataSource": {
                  "commonDataSource": "USER"
                },
                "minCharactersTrigger": 1
              }
            ]
          }
        }
      ]
    }
  ]
}

Wypełnianie elementów z zewnętrznego źródła danych

Menu mogą też zawierać elementy z zewnętrznego źródła danych. Aby użyć zewnętrznego źródła danych, określ pole remoteDataSource w obiekcie DataSourceConfig, który zawiera funkcję wysyłającą zapytania i zwracającą elementy ze źródła danych.

Aby zmniejszyć liczbę żądań wysyłanych do zewnętrznego źródła danych, możesz uwzględnić sugerowane elementy, które pojawiają się w menu, zanim użytkownicy zaczną w nim pisać. Aby wypełnić sugerowane elementy z zewnętrznego źródła danych, określ statyczne obiekty SelectionItem.

Poniższy kod pokazuje menu, które wysyła zapytania do zewnętrznego źródła danych i wypełnia elementy z tego źródła:

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "crm_leads",
            "type": "DROPDOWN",
            "label": "Select CRM Lead",
            "dataSourceConfigs": [
              {
                "remoteDataSource": {
                  "function": "getCrmLeads"
                },
                "minCharactersTrigger": 2
              }
            ],
            "items": [
              {
                "text": "Suggested Lead 1",
                "value": "lead-1"
              }
            ]
          }
        }
      ]
    }
  ]
}

Pełny przykład pokazujący, jak zwracać sugerowane elementy, znajdziesz w sekcji Sugerowanie elementów do wyboru.

Dodawanie menu wielokrotnego wyboru

Aby dostosować elementy wyboru lub umożliwić użytkownikom wybieranie elementów z dynamicznego źródła danych, aplikacje do Google Chat mogą używać menu wielokrotnego wyboru, które są rodzajem widżetu SelectionInput. Na przykład na karcie poniżej wyświetla się menu wielokrotnego wyboru, w którym użytkownicy mogą dynamicznie wybierać kontakty z listy:

Elementy menu wielokrotnego wyboru możesz wypełnić danymi z tych źródeł:

  • Dane Google Workspace, które obejmują użytkowników lub pokoje czatu, do których należy użytkownik. W menu wyświetlane są tylko elementy z tej samej organizacji Google Workspace.
  • zewnętrzne źródła danych, takie jak relacyjna baza danych; Możesz na przykład użyć menu wielokrotnego wyboru, aby pomóc użytkownikowi wybrać pozycję z listy potencjalnych sprzedaży z systemu zarządzania relacjami z klientami (CRM).

Wypełnianie elementów danymi ze źródła danych Google Workspace

Aby używać źródeł danych Google Workspace, określ pole platformDataSource w widżecie SelectionInput. W przeciwieństwie do innych typów danych wejściowych wyboru pomijasz obiekty SelectionItem, ponieważ te elementy wyboru są dynamicznie pobierane z Google Workspace.

Poniższy kod przedstawia menu wielokrotnego wyboru użytkowników Google Workspace. Aby wypełnić listę użytkowników, pole wyboru ustawia parametr commonDataSource na wartość USER:

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

Poniższy kod pokazuje menu wielokrotnego wyboru pokoi czatu. Aby wypełnić pokoje, dane wejściowe wyboru określają pole hostAppDataSource. Menu wielokrotnego wyboru ustawia też właściwość defaultToCurrentSpace na true, co sprawia, że bieżący pokój jest domyślnym wyborem w menu:

JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Wypełnianie elementów z zewnętrznego źródła danych

Menu wielokrotnego wyboru mogą też wypełniać elementy z zewnętrznego źródła danych. Aby użyć zewnętrznego źródła danych, określ pole externalDataSource w widżecie SelectionInput, które zawiera funkcję wysyłającą zapytania i zwracającą elementy ze źródła danych.

Aby zmniejszyć liczbę żądań wysyłanych do zewnętrznego źródła danych, możesz uwzględnić sugerowane elementy, które pojawiają się w menu wielokrotnego wyboru, zanim użytkownicy zaczną wpisywać tekst w menu. Możesz na przykład wyświetlić użytkownikowi ostatnio wyszukiwane kontakty. Aby wypełnić sugerowane elementy z zewnętrznego źródła danych, określ statyczne obiekty SelectionItem.

Poniższy przykładowy kod pokazuje menu wielokrotnego wyboru, które wysyła zapytania i wypełnia elementy z zewnętrznego źródła danych:

Node.js

node/chat/selection-input/index.js
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: FUNCTION_URL },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getSuggestedContact("3")]
}

Zastąp FUNCTION_URL punktem końcowym HTTP, który wysyła zapytania do zewnętrznego źródła danych.

Python

python/chat/selection-input/main.py
'selectionInput': {
  'name': "contacts",
  'type': "MULTI_SELECT",
  'label': "Selected contacts",
  'multiSelectMaxSelectedItems': 3,
  'multiSelectMinQueryLength': 1,
  'externalDataSource': { 'function': FUNCTION_URL },
  # Suggested items loaded by default.
  # The list is static here but it could be dynamic.
  'items': [get_suggested_contact("3")]
}

Zastąp FUNCTION_URL punktem końcowym HTTP, który wysyła zapytania do zewnętrznego źródła danych.

Java

java/chat/selection-input/src/main/java/com/google/chat/selectionInput/App.java
.setSelectionInput(new GoogleAppsCardV1SelectionInput()
  .setName("contacts")
  .setType("MULTI_SELECT")
  .setLabel("Selected contacts")
  .setMultiSelectMaxSelectedItems(3)
  .setMultiSelectMinQueryLength(1)
  .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  .setItems(List.of(getSuggestedContact("3")))))))))));

Zastąp FUNCTION_URL punktem końcowym HTTP, który wysyła zapytania do zewnętrznego źródła danych.

Google Apps Script

Ten przykład wysyła wiadomość z kartą, zwracając kod JSON karty. Możesz też użyć usługi kart Apps Script.

apps-script/chat/selection-input/selection-input.gs
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "queryContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getSuggestedContact("3")]
}

Pełny przykład pokazujący, jak zwracać sugerowane elementy, znajdziesz w sekcji Sugerowanie elementów do wyboru.

Odbieranie danych z interaktywnych widżetów

Za każdym razem, gdy użytkownik kliknie przycisk, wywoływane jest działanie aplikacji do Google Chat z informacjami o interakcji. W obiekcie commonEventObject ładunku zdarzenia obiekt formInputs zawiera wszystkie wartości wprowadzone przez użytkownika.

Możesz pobrać wartości z obiektu event.commonEventObject.formInputs.WIDGET_NAME, gdzie WIDGET_NAME to pole name określone dla widżetu. Wartości są zwracane jako określony typ danych widżetu.

Poniżej znajduje się fragment obiektu zdarzenia, w którym użytkownik wpisał wartości dla każdego widżetu:

{
  "commonEventObject": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Aby otrzymać dane, aplikacja Google Chat obsługuje obiekt zdarzenia, aby uzyskać wartości wpisane przez użytkowników w widżetach. W tabeli poniżej pokazano, jak uzyskać wartość danego widżetu danych wejściowych formularza. W tabeli podano typ danych akceptowany przez każdy widżet, miejsce przechowywania wartości w obiekcie zdarzenia oraz przykładową wartość.

Widżet do wprowadzania danych w formularzu Typ danych wejściowych Wartość wejściowa z obiektu zdarzenia Przykładowa wartość
textInput stringInputs event.commonEventObject.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs Aby uzyskać pierwszą lub jedyną wartość, event.commonEventObject.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker, który akceptuje tylko daty. dateInput event.commonEventObject.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

Po otrzymaniu danych aplikacja do Google Chat może wykonać dowolną z tych czynności:

  • W przypadku kart zawierających menu wielokrotnego wyboru wypełniaj lub sugeruj elementy na podstawie tego, co użytkownik wpisuje w menu.
  • Przenieś dane na inną kartę, aby użytkownik mógł sprawdzić swoje informacje lub przejść do następnej sekcji formularza.
  • Odpowiedz użytkownikowi, aby potwierdzić, że formularz został wypełniony.

Sugerowanie elementów wyboru

Jeśli karta zawiera menu wielokrotnego wyboru lub menu, które wypełnia elementy z zewnętrznego źródła danych, aplikacja Google Chat może zwracać sugerowane elementy na podstawie tego, co użytkownicy wpisują w menu. Jeśli na przykład użytkownik zacznie wpisywać Atl w menu, które zawiera miasta w Stanach Zjednoczonych, aplikacja do Google Chat może automatycznie zasugerować Atlanta, zanim użytkownik skończy wpisywać. Aplikacja Google Chat może zasugerować maksymalnie 100 elementów.

Aby sugerować i dynamicznie wypełniać elementy w danych wejściowych wyboru, widżet SelectionInput na karcie musi określać funkcję, która wysyła zapytanie do zewnętrznego źródła danych. W przypadku menu wielokrotnego wyboru określasz pole externalDataSource. W przypadku menu określasz pole remoteDataSource w obiekcie DataSourceConfig.

Możesz też skonfigurować liczbę znaków, które użytkownik musi wpisać, zanim menu wyświetli sugestie. W przypadku menu wielokrotnego wyboru ustaw pole multiSelectMinQueryLength. W przypadku menu ustaw pole min_characters_trigger w DataSourceConfig.

Aby zwrócić sugerowane elementy, funkcja musi wykonać te czynności:

  1. Obsługiwać obiekt zdarzenia, który aplikacja do obsługi czatu otrzymuje, gdy użytkownicy wpisują tekst w menu.
  2. Z obiektu zdarzenia pobierz wartość wpisaną przez użytkownika, która jest reprezentowana w polu event.commonEventObject.parameters["autocomplete_widget_query"].
  3. Wyślij zapytanie do źródła danych, używając wartości wprowadzonej przez użytkownika, aby uzyskać co najmniej 1 SelectionItems do zasugerowania użytkownikowi.
  4. Zwróć sugerowane elementy, zwracając działanie RenderActions z obiektem modifyCard.

Poniższy przykładowy kod pokazuje, jak aplikacja Google Chat dynamicznie sugeruje elementy w menu wielokrotnego wyboru na karcie. Gdy użytkownik wpisze coś w menu, funkcja lub punkt końcowy podany w polu externalDataSource widżetu wysyła zapytanie do zewnętrznego źródła danych i sugeruje elementy, które użytkownik może wybrać.

Node.js

node/chat/selection-input/index.js
/**
 * Web app that responds to events sent from a Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
app.post('/', async (req, res) => {
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.json(queryContacts(req.body));
  }

  // Replies with a card that contains the multiselect menu.
  return res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: FUNCTION_URL },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
});

/**
 * Get contact suggestions based on text typed by users.
 *
 * @param {Object} event the event object that contains the user's query
 * @return {Object} suggestions
 */
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Zastąp FUNCTION_URL punktem końcowym HTTP, który wysyła zapytania do zewnętrznego źródła danych.

Python

python/chat/selection-input/main.py
@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: The response
  """
  # Stores the Google Chat event
  chatEvent = request.get_json().get('chat')

  # Handle user interaction with multiselect.
  if chatEvent.get('widgetUpdatedPayload') is not None:
    return json.jsonify(query_contacts(request.get_json()))

  # Replies with a card that contains the multiselect menu.
  return json.jsonify({ 'hostAppDataAction': { 'chatDataAction': { 'createMessageAction': {
    'message': { 'cardsV2': [{
      'cardId': "contactSelector",
      'card': { 'sections':[{ 'widgets': [{
        'selectionInput': {
          'name': "contacts",
          'type': "MULTI_SELECT",
          'label': "Selected contacts",
          'multiSelectMaxSelectedItems': 3,
          'multiSelectMinQueryLength': 1,
          'externalDataSource': { 'function': FUNCTION_URL },
          # Suggested items loaded by default.
          # The list is static here but it could be dynamic.
          'items': [get_suggested_contact("3")]
        }
      }]}]}
    }]}
  }}}})


def query_contacts(event: dict) -> dict:
  """Get contact suggestions based on text typed by users.

  Args:
      event (Mapping[str, Any]): The event object that contains the user's query

  Returns:
      Mapping[str, Any]: The response with contact suggestions.
  """
  query = event.get("commonEventObject").get("parameters").get("autocomplete_widget_query")
  return { 'action': { 'modifyOperations': [{ 'updateWidget': { 'selectionInputWidgetSuggestions': { 'suggestions': list(
    filter(lambda e: query is None or query in e["text"], [
      # The list is static here but it could be dynamic.
      get_suggested_contact("1"), get_suggested_contact("2"), get_suggested_contact("3"), get_suggested_contact("4"), get_suggested_contact("5")
    # Only return items based on the query from the user
    ])
  )}}}]}}


def get_suggested_contact(id: str) -> dict:
  """Generate a suggested contact given an ID.

  Args:
      id (str): The ID of the contact to return.

  Returns:
      Mapping[str, Any]: The contact formatted as a selection item in the menu.
  """
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

Zastąp FUNCTION_URL punktem końcowym HTTP, który wysyła zapytania do zewnętrznego źródła danych.

Java

java/chat/selection-input/src/main/java/com/google/chat/selectionInput/App.java
@SpringBootApplication
@RestController
// Web app that responds to events sent from a Google Chat space.
public class App {
  private static final String FUNCTION_URL = "your-function-url";

  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /**
   * Handle requests from Google Chat
   * 
   * @param event the event object sent by Google Chat
   * @return The response to be sent back to Google Chat
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    // Stores the Google Chat event
    JsonNode chatEvent = event.at("/chat");

    // Handle user interaction with multiselect.
    if (!chatEvent.at("/widgetUpdatedPayload").isEmpty()) {
      return queryContacts(event);
    }

    // Replies with a card that contains the multiselect menu.
    Message message = new Message().setCardsV2(List.of(new CardWithId()
      .setCardId("contactSelector")
      .setCard(new GoogleAppsCardV1Card()
        .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(new GoogleAppsCardV1Widget()
          .setSelectionInput(new GoogleAppsCardV1SelectionInput()
            .setName("contacts")
            .setType("MULTI_SELECT")
            .setLabel("Selected contacts")
            .setMultiSelectMaxSelectedItems(3)
            .setMultiSelectMinQueryLength(1)
            .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
            // Suggested items loaded by default.
            // The list is static here but it could be dynamic.
            .setItems(List.of(getSuggestedContact("3")))))))))));

    return new GenericJson() {{
      put("hostAppDataAction", new GenericJson() {{
        put("chatDataAction", new GenericJson() {{
          put("createMessageAction", new GenericJson() {{
            put("message", message);
          }});
        }});
      }});
    }};
  }

  /**
   * Get contact suggestions based on text typed by users.
   *
   * @param event the event object that contains the user's query.
   * @return The response with contact suggestions.
   */
  GenericJson queryContacts(JsonNode event) throws Exception {
    String query = event.at("/commonEventObject/parameters/autocomplete_widget_query").asText();
    List<GoogleAppsCardV1SelectionItem> suggestions = List.of(
      // The list is static here but it could be dynamic.
      getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
    // Only return items based on the query from the user
    ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList();

    return new GenericJson() {{
      put("action", new GenericJson() {{
        put("modifyOperations", List.of(new GenericJson() {{
          put("updateWidget", new GenericJson() {{
            put("selectionInputWidgetSuggestions", new GenericJson() {{
              put("suggestions", suggestions);
            }});
          }});
        }}));
      }});
    }};
  }

  /**
   * Generate a suggested contact given an ID.
   * 
   * @param id The ID of the contact to return.
   * @return The contact formatted as a selection item in the menu.
   */
  GoogleAppsCardV1SelectionItem getSuggestedContact(String id) {
    return new GoogleAppsCardV1SelectionItem()
      .setValue(id)
      .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")
      .setText("Contact " + id);
  }
}

Zastąp FUNCTION_URL punktem końcowym HTTP, który wysyła zapytania do zewnętrznego źródła danych.

Google Apps Script

Ten przykład wysyła wiadomość z kartą, zwracając kod JSON karty. Możesz też użyć usługi kart Apps Script.

apps-script/chat/selection-input/selection-input.gs
/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Przenoszenie danych na inną kartę

Gdy użytkownik prześle informacje z karty, może być konieczne zwrócenie dodatkowych kart, aby:

  • Ułatw użytkownikom wypełnianie dłuższych formularzy, tworząc osobne sekcje.
  • Pozwól użytkownikom wyświetlić podgląd i potwierdzić informacje z początkowej karty, aby mogli sprawdzić swoje odpowiedzi przed przesłaniem.
  • Dynamicznie wypełniaj pozostałe części formularza. Na przykład, aby zachęcić użytkowników do utworzenia spotkania, aplikacja Google Chat może wyświetlić początkową kartę z prośbą o podanie powodu spotkania, a następnie wypełnić kolejną kartę z dostępnymi godzinami na podstawie typu spotkania.

Aby przenieść dane wejściowe z początkowej karty, możesz utworzyć widżet button za pomocą actionParameters, które zawierają name widżetu i wartość wprowadzoną przez użytkownika, jak w tym przykładzie:

Node.js

node/chat/contact-form-app/index.js
{ buttonList: { buttons: [{
  text: "SUBMIT",
  onClick: { action: {
    function: FUNCTION_URL,
    parameters: [
      { key: "actionName", value: "submitDialog" },
      // Pass input values as parameters for last dialog step (submission)
      { key: "contactName", value: name },
      { key: "contactBirthdate", value: birthdate },
      { key: "contactType", value: type }
    ]
  }}
}]}}

Zastąp FUNCTION_URL punktem końcowym HTTP, który obsługuje kliknięcia przycisku.

Python

python/chat/contact-form-app/main.py
{ 'buttonList': { 'buttons': [{
  'text': "SUBMIT",
  'onClick': { 'action': {
    'function': FUNCTION_URL,
    'parameters': [
      { 'key': "actionName", 'value': "submitDialog" },
      # Pass input values as parameters for last dialog step (submission)
      { 'key': "contactName", 'value': name },
      { 'key': "contactBirthdate", 'value': birthdate },
      { 'key': "contactType", 'value': type }
    ]
  }}
}]}}

Zastąp FUNCTION_URL punktem końcowym HTTP, który obsługuje kliknięcia przycisku.

Java

java/chat/contact-form-app/src/main/java/com/google/chat/contact/App.java
new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(
  new GoogleAppsCardV1Button()
    .setText("SUBMIT")
    .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
      .setFunction(FUNCTION_URL)
      .setParameters(List.of(
        new GoogleAppsCardV1ActionParameter().setKey("actionName").setValue("submitDialog"),
        // Pass input values as parameters for last dialog step (submission)
        new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
        new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
        new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))))));

Zastąp FUNCTION_URL punktem końcowym HTTP, który obsługuje kliknięcia przycisku.

Google Apps Script

Ten przykład wysyła wiadomość z kartą, zwracając kod JSON karty. Możesz też użyć usługi kart Apps Script.

apps-script/chat/contact-form-app/Code.gs
{ buttonList: { buttons: [{
  text: "SUBMIT",
  onClick: { action: {
    function: "submitDialog",
    // Pass input values as parameters for last dialog step (submission)
    parameters: [
      { key: "contactName", value: name },
      { key: "contactBirthdate", value: birthdate },
      { key: "contactType", value: type }
    ]
  }}
}]}}

Gdy użytkownik kliknie przycisk, aplikacja Google Chat otrzyma obiekt zdarzenia, z którego możesz pobrać dane.

Odpowiadanie na przesłany formularz

Po otrzymaniu danych z wiadomości z kartą lub okna dialogowego aplikacja do Google Chat odpowiada, potwierdzając odbiór lub zwracając błąd.

W tym przykładzie aplikacja do Google Chat wysyła wiadomość tekstową, aby potwierdzić, że otrzymała formularz przesłany z wiadomości z kartą.

Node.js

node/chat/contact-form-app/index.js
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
  text: "✅ " + event.commonEventObject.parameters["contactName"] + " has been added to your contacts."
}}}}};

Python

python/chat/contact-form-app/main.py
return { 'hostAppDataAction': { 'chatDataAction': { 'createMessageAction': { 'message': {
  'text': "✅ " + event.get('commonEventObject').get('parameters')["contactName"] + " has been added to your contacts."
}}}}}

Java

java/chat/contact-form-app/src/main/java/com/google/chat/contact/App.java
return new GenericJson() {{
  put("hostAppDataAction", new GenericJson() {{
    put("chatDataAction", new GenericJson() {{
      put("createMessageAction", new GenericJson() {{
        put("message", new Message()
          .setText( "✅ " + event.at("/commonEventObject/parameters/contactName").asText() +
                    " has been added to your contacts."));
      }});
    }});
  }});
}};

Google Apps Script

Ten przykład wysyła wiadomość z kartą, zwracając kod JSON karty. Możesz też użyć usługi kart Apps Script.

apps-script/chat/contact-form-app/Code.gs
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
  text: "✅ " + event.commonEventObject.parameters["contactName"] + " has been added to your contacts."
}}}}};

Aby przetworzyć i zamknąć okno, zwróć obiekt RenderActions, który określa, czy chcesz wysłać wiadomość z potwierdzeniem, zaktualizować pierwotną wiadomość lub kartę, czy po prostu zamknąć okno. Instrukcje znajdziesz w artykule Zamykanie okna.

Rozwiązywanie problemów

Ta sekcja zawiera instrukcje rozwiązywania problemów z określonymi kodami błędów i zachowaniami w czasie działania podczas interakcji z oknami w Google Chat.

Interakcje z oknem zwracają błąd „Podczas wywoływania dodatku wystąpił nieokreślony błąd”

Jeśli podczas interakcji z oknem dialogowym zobaczysz dzienniki błędów z komunikatem „Nieokreślony błąd podczas wywoływania dodatku” i kodem 13, zwykle oznacza to błąd wewnętrzny lub że punkt końcowy HTTP aplikacji Google Chat nie mógł przetworzyć żądania lub zwrócić prawidłowej odpowiedzi.

Aby rozwiązać ten problem:

  • Sprawdź logi punktu końcowego HTTP pod kątem nieobsługiwanych wyjątków lub awarii.
  • Sprawdź, czy Twój punkt końcowy odpowiada na żądania w ciągu 30 sekund. Jeśli wykonanie punktu końcowego trwa dłużej niż 30 sekund, Google Chat nie może przetworzyć odpowiedzi i interakcja się nie powiedzie. Więcej informacji znajdziesz w artykule Limity i sprawdzone metody.
  • Upewnij się, że punkt końcowy zwraca prawidłową odpowiedź. W przypadku przesyłania okien punkt końcowy musi zwracać obiekt RenderActions w prawidłowym formacie JSON. Jeśli odpowiedź jest nieprawidłowo sformatowana lub nie zawiera wymaganych pól, interakcja z oknem może się nie powieść.

Gdy aplikacja Google Chat lub karta zwraca błąd, interfejs Google Chat wyświetla komunikat „Coś poszło nie tak”. lub „Nie udało się przetworzyć żądania”. Czasami interfejs Google Chat nie wyświetla żadnego komunikatu o błędzie, ale aplikacja lub karta Google Chat generuje nieoczekiwany wynik, np. wiadomość na karcie może się nie pojawić.

Chociaż komunikat o błędzie może nie wyświetlać się w interfejsie Google Chat, opisowe komunikaty o błędach i dane dziennika są dostępne, aby pomóc Ci naprawić błędy, gdy włączone jest rejestrowanie błędów w aplikacjach Google Chat. Pomoc dotyczącą wyświetlania, debugowania i naprawiania błędów znajdziesz w artykule Rozwiązywanie problemów z Google Chat.

Aplikacje do obsługi czatu, które nie są dodatkami: odczytywanie danych formularza wprowadzonych przez użytkowników na kartach.

Poniższa dokumentacja dotyczy aplikacji do Google Chat, które nie są dodatkami do Google Workspace. Aby dowiedzieć się, jak przenieść aplikację do Google Chat, która nie jest dodatkiem, przeczytaj artykuł Przekształcanie aplikacji do Google Chat w dodatek do Google Workspace.

Tworzenie formularzy za pomocą kart

Poniższy kod przedstawia przykład aplikacji do Google Chat, która nie jest dodatkiem i używa formularza kontaktowego z polem tekstowym, selektorem daty i godziny oraz polem wyboru:

Node.js

node/contact-form-app/index.js
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

Python

python/contact-form-app/main.py
# The section of the contact card that contains the form input widgets. Used in a dialog and card message.
# To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": False
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": False
        }
      ]
    }
  }
]

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
// The section of the contact card that contains the form input widgets. Used in a dialog and card message.
// To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
final static private List<GoogleAppsCardV1Widget> CONTACT_FORM_WIDGETS = List.of(
  new GoogleAppsCardV1Widget().setTextInput(new GoogleAppsCardV1TextInput()
    .setName("contactName")
    .setLabel("First and last name")
    .setType("SINGLE_LINE")),
  new GoogleAppsCardV1Widget().setDateTimePicker(new GoogleAppsCardV1DateTimePicker()
    .setName("contactBirthdate")
    .setLabel("Birthdate")
    .setType("DATE_ONLY")),
  new GoogleAppsCardV1Widget().setSelectionInput(new GoogleAppsCardV1SelectionInput()
    .setName("contactType")
    .setLabel("Contact type")
    .setType("RADIO_BUTTON")
    .setItems(List.of(
      new GoogleAppsCardV1SelectionItem()
        .setText("Work")
        .setValue("Work")
        .setSelected(false),
      new GoogleAppsCardV1SelectionItem()
        .setText("Personal")
        .setValue("Personal")
        .setSelected(false)))));

Google Apps Script

apps-script/contact-form-app/contactForm.gs
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

Odbieranie danych z interaktywnych widżetów

Gdy użytkownicy klikną przycisk, aplikacje do Google Chat, które nie są dodatkami, otrzymują zdarzenie interakcji zależne od lokalizacji przycisku:

  • Jeśli przycisk znajduje się w wiadomości lub oknie, aplikacje Google Chat, które nie są dodatkami, otrzymują zdarzenie interakcji CARD_CLICKED zawierające informacje o interakcji. Ładunek zdarzeń interakcji CARD_CLICKED zawiera obiekt common.formInputs (event.common.formInputs) z dowolnymi wartościami wprowadzonymi przez użytkownika.

    Możesz pobrać wartości z obiektu common.formInputs.WIDGET_NAME, gdzie WIDGET_NAME to pole name określone dla widżetu. Wartości są zwracane jako określony typ danych widżetu (reprezentowany jako obiekt Inputs).

    Poniżej znajduje się fragment zdarzenia interakcji CARD_CLICKED, w którym użytkownik wpisał wartości dla każdego widżetu:

    HTTP

    {
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

    Google Apps Script 

    {
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "": { "stringInputs": {
      "value": ["Kai 0"]
    }}},
    "contactBirthdate": { "": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }}},
      "contactType": { "": { "stringInputs": {
      "value": ["Personal"]
    }}}
  }}
}

  • Jeśli przycisk znajduje się na stronie głównej, aplikacje do Google Chat, które nie są dodatkami, otrzymują zdarzenie interakcji SUBMIT_FORM. Ładunek zdarzenia interakcji zawiera obiekt commonEventObject.formInputs (event.commonEventObject.formInputs) z wartościami wprowadzonymi przez użytkownika.

    Możesz pobrać wartości z obiektu commonEventObject.formInputs.WIDGET_NAME, gdzie WIDGET_NAME to pole name określone dla widżetu. Wartości są zwracane jako określony typ danych widżetu (reprezentowany jako obiekt Inputs).

    Poniżej znajduje się fragment zdarzenia interakcji SUBMIT_FORM, w którym użytkownik wpisał wartości dla każdego widżetu:

    HTTP

    {
  "type": "SUBMIT_FORM",
  "commonEventObject": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

    Google Apps Script 

    {
  "type": "SUBMIT_FORM",
  "commonEventObject": { "formInputs": {
    "contactName": { "": { "stringInputs": {
      "value": ["Kai 0"]
    }}},
    "contactBirthdate": { "": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }}},
      "contactType": { "": { "stringInputs": {
      "value": ["Personal"]
    }}}
  }}
}

Aby otrzymać dane, aplikacja do Google Chat, która nie jest dodatkiem, obsługuje zdarzenie interakcji, aby uzyskać wartości wprowadzane przez użytkowników w widżetach. W tabeli poniżej pokazujemy, jak uzyskać wartość danego widżetu wejściowego formularza. W tabeli znajdziesz informacje o typach danych, które obsługuje dany widżet, o miejscu przechowywania wartości w zdarzeniu interakcji oraz przykładową wartość.

Widżet do wprowadzania danych w formularzu Typ danych wejściowych Wartość wejściowa ze zdarzenia interakcji Przykładowa wartość
textInput stringInputs event.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs Aby uzyskać pierwszą lub jedyną wartość, event.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker, który akceptuje tylko daty. dateInput event.common.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

Przenoszenie danych na inną kartę

Aby przenieść dane wejściowe z początkowej karty w aplikacji Google Chat, która nie jest dodatkiem, utwórz widżet button z actionParameters, które zawierają name widżetu i wartość wprowadzoną przez użytkownika, jak w tym przykładzie:

Node.js

node/contact-form-app/index.js
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Python

python/contact-form-app/main.py
'buttonList': { 'buttons': [{
  'text': "Submit",
  'onClick': { 'action': {
    'function': "submitForm",
    'parameters': [{
      'key': "contactName", 'value': name }, {
      'key': "contactBirthdate", 'value': birthdate }, {
      'key': "contactType", 'value': type
    }]
  }}
}]}

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
  .setText("Submit")
  .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
    .setFunction("submitForm")
    .setParameters(List.of(
      new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
      new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
      new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))));

Google Apps Script

apps-script/contact-form-app/main.gs
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Gdy użytkownik kliknie przycisk, aplikacja Google Chat, która nie jest dodatkiem, otrzyma zdarzenie interakcji CARD_CLICKED, z którego możesz pobrać dane.

Odpowiadanie na przesłany formularz

W tym przykładzie aplikacja do Google Chat, która nie jest dodatkiem, wysyła wiadomość tekstową, aby potwierdzić, że otrzymała formularz przesłany z okna lub wiadomości z kartą:

Node.js

node/contact-form-app/index.js
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

Python

python/contact-form-app/main.py
contact_name = event.get('common').get('parameters')["contactName"]
# Checks to make sure the user entered a contact name.
# If no name value detected, returns an error message.
error_message = "Don't forget to name your new contact!"
if contact_name == "" and "SUBMIT_DIALOG" == event.get('dialogEventType'):
  return { 'actionResponse': {
    'type': "DIALOG",
    'dialogAction': { 'actionStatus': {
      'statusCode': "INVALID_ARGUMENT",
      'userFacingMessage': error_message
    }}
  }}

Java

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
String contactName = event.at("/common/parameters/contactName").asText();
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
String errorMessage = "Don't forget to name your new contact!";
if (contactName.isEmpty() && event.at("/dialogEventType") != null && "SUBMIT_DIALOG".equals(event.at("/dialogEventType").asText())) {
  return new Message().setActionResponse(new ActionResponse()
    .setType("DIALOG")
    .setDialogAction(new DialogAction().setActionStatus(new ActionStatus()
      .setStatusCode("INVALID_ARGUMENT")
      .setUserFacingMessage(errorMessage))));
}

Google Apps Script

apps-script/contact-form-app/main.gs
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

Aby przetworzyć i zamknąć okno w aplikacji Google Chat, która nie jest dodatkiem, zwróć obiekt ActionResponse, który określa, czy chcesz wysłać wiadomość z potwierdzeniem, zaktualizować pierwotną wiadomość lub kartę, czy po prostu zamknąć okno. Instrukcje znajdziesz w artykule Zamykanie okna.