Informacje o procesie wpisywane przez użytkowników

Z tego przewodnika dowiesz się, jak otrzymywać i odczytywać informacje wpisywane przez użytkowników w wiadomościach z kartami i oknach dialogowych. Użytkownicy mogą wprowadzać dane, które aplikacje do obsługi czatu otrzymują, odczytują i na które odpowiadają. Oto widżety, które umożliwiają użytkownikom wpisywanie informacji:

  • TextInput – możliwość swobodnego wpisywania tekstu, który obsługuje też sugestie.
  • SelectionInput – w przypadku elementów listy i menu, takich jak pola wyboru, przyciski i menu.
  • DateTimePicker w przypadku wpisów daty i godziny.

Dzięki odbieraniu danych wejściowych od użytkowników aplikacje do obsługi czatu mogą wykonywać te działania:

  • Aktualizuj zgłoszenia do obsługi klienta.
  • tworzyć zamówienia,
  • Uwierzytelniaj w usługach internetowych.

Jak działa odbieranie danych

Aplikacja do obsługi czatu prezentuje informacje użytkownikowi w formie okna lub wiadomości na karcie. W tym przykładzie okno dialogowe prosi użytkownika o wpisanie informacji o kontakcie za pomocą widżetów TextInput i SelectionInput:

Okno z różnymi widżetami.

Gdy skończysz, aplikacja do obsługi czatu otrzyma w formacie JSON dane wpisane przez użytkowników w oknie oraz zdarzenie interakcji, gdzie:

Aby uzyskać dane o treściach wprowadzonych przez użytkowników, użyj pola Event.common.formInputs w ładunku zdarzenia. Pole formInputs to mapa, w której klucze to identyfikatory ciągów znaków przypisane do każdego widżetu, a wartości reprezentują dane wejściowe użytkownika dotyczące każdego widżetu. Różne obiekty reprezentują różne typy danych wejściowych. Na przykład Event.common.formInputs.stringInputs reprezentuje dane wejściowe w postaci ciągu znaków.

Aplikacja może korzystać z pierwszej wartości wpisanej przez użytkownika w adresie event.common.formInputs.NAME.stringInputs.value[0], gdzie NAME to pole name widżetu TextInput.

Odbieranie danych z kart

Gdy użytkownik wpisze dane w wiadomości na karcie, aplikacja do obsługi czatu otrzyma zdarzenie interakcji z Google Chat, jak w tym przykładzie:

JSON

{
  "type": enum (EventType),
  "eventTime": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,
  "common": {

    // Represents user data entered in a card.
    "formInputs": {

      // Represents user data entered for a specific field in a card.
      "NAME": {

        // Represents string data entered in a card, like text input fields
        // and check boxes.
        "stringInputs": {

          // An array of strings entered by the user in a card.
          "value": [
            string
          ]
        }
      }
    },
    "parameters": {
      string: string,
      ...
    },
    "invokedFunction": string
  }
}

Odbieranie danych z okien dialogowych

Gdy użytkownik przesyła dane w oknie, aplikacja do obsługi czatu otrzymuje inne zdarzenie interakcji z aplikacją, np.:

JSON

{
  "type": enum (EventType),
  "eventTime": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,

  // Indicates that this event is dialog-related.
  "isDialogEvent": true,

  // Indicates that a user clicked a button, and all data
  // they entered in the dialog is included in Event.common.formInputs.
  "dialogEventType": "SUBMIT_DIALOG",
  "common": {
    "userLocale": string,
    "hostApp": enum (HostApp),
    "platform": enum (Platform),
    "timeZone": {
      object (TimeZone)
    },

    // Represents user data entered in a dialog.
    "formInputs": {

      // Represents user data entered for a specific field in a dialog.
      "NAME": {

        // Represents string data entered in a dialog, like text input fields
        // and check boxes.
        "stringInputs": {

          // An array of strings entered by the user in a dialog.
          "value": [
            string
          ]
        }
      }
    },
    "parameters": {
      string: string,
      ...
    },
    "invokedFunction": string
  }
}

Reagowanie na dane zebrane z wiadomości karty lub okna

Po otrzymaniu danych z wiadomości na karcie lub okna dialogowego aplikacja Google Chat potwierdza odbiór lub zwraca błąd. W obu tych przypadkach zwracany jest sygnał ActionResponse:

  • Aby potwierdzić odbiór, w odpowiedzi prześlij parametr ActionResponse z "actionStatus": "OK".
  • Aby zwrócić błąd, w odpowiedzi użyj parametru ActionResponse, który zawiera "actionStatus": "ERROR MESSAGE".

Przykład

W tym przykładzie sprawdzamy obecność wartości name. Jeśli go brakuje, aplikacja zwraca błąd. Jeśli ta opcja jest dostępna, aplikacja potwierdza odbiór danych formularza i zamyka okno.

Node.js

/**
 * Checks for a form input error, the absence of
 * a "name" value, and returns an error if absent.
 * Otherwise, confirms successful receipt of a dialog.
 *
 * Confirms successful receipt of a dialog.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function receiveDialog(event) {

  // Checks to make sure the user entered a name
  // in a dialog. If no name value detected, returns
  // an error message.
  if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] == "") {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "Don't forget to name your new contact!"
        }
      }
    });

  // Otherwise the app indicates that it received
  // form data from the dialog. Any value other than "OK"
  // gets returned as an error. "OK" is interpreted as
  // code 200, and the dialog closes.
  } else {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    });
  }
}

Google Apps Script

/**
 * Checks for a form input error, the absence of
 * a "name" value, and returns an error if absent.
 * Otherwise, confirms successful receipt of a dialog.
 *
 * Confirms successful receipt of a dialog.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function receiveDialog(event) {

  // Checks to make sure the user entered a name
  // in a dialog. If no name value detected, returns
  // an error message.
  if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] == "") {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "Don't forget to name your new contact!"
        }
      }
    };

  // Otherwise the app indicates that it received
  // form data from the dialog. Any value other than "OK"
  // gets returned as an error. "OK" is interpreted as
  // code 200, and the dialog closes.
  } else {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    };
  }
}

Python

def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Checks for a form input error, the absence of a "name" value, and returns
     an error if absent. Otherwise, confirms successful receipt of a dialog.

  Args:
      event (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: the response.
  """

  if common := event.get('common'):
    if form_inputs := common.get('formInputs'):
      if contact_name := form_inputs.get('WIDGET_NAME'):
        if string_inputs := contact_name.get('stringInputs'):
          if name := string_inputs.get('value')[0]:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'OK'
                }
              }
            }
          else:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'Don\'t forget to name your new contact!'
                }
              }
            }

Rozwiązywanie problemów

Gdy aplikacja lub karta Google Chat zwróci błąd, w interfejsie czatu pojawi się komunikat „Coś poszło nie tak” lub „Nie udało się przetworzyć Twojego żądania”. Czasami w interfejsie Google Chat nie pojawia się żaden komunikat o błędzie, ale aplikacja lub karta Google Chat mogą dać nieoczekiwany wynik, na przykład komunikat na karcie.

Mimo że komunikat o błędzie może nie wyświetlić się w interfejsie Google Chat, dostępne są opisowe komunikaty o błędach i dane dziennika, które pomogą Ci naprawić błędy występujące po włączeniu rejestrowania błędów w aplikacjach do obsługi czatu. Więcej informacji o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z Google Chat i rozwiązywanie problemów.