Informacje o procesie wpisywane przez użytkowników

Ten przewodnik opisuje, jak otrzymywać i odczytywać informacje, które użytkownicy wpisują w wiadomościach na karcie i w oknach dialogowych. Użytkownicy mogą wprowadzać dane, które aplikacje do obsługi czatu otrzymują i odczytują oraz na które reaguje. Widżety umożliwiające użytkownikom wpisywanie informacji to między innymi:

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

---

Za pomocą Kreatora kart możesz projektować karty JSON i wyświetlać ich podgląd na potrzeby aplikacji Google Chat:

Otwórz kreator kart

---

Otrzymywanie danych wejściowych od użytkowników umożliwia aplikacjom Google Chat między innymi:

• Aktualizowanie zgłoszeń do działu obsługi klienta.
• tworzyć zamówienia,
• Uwierzytelniaj za pomocą usług 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 z prośbą o podanie informacji o kontakcie za pomocą widżetów TextInput i SelectionInput:

Gdy skończysz, aplikacja Google Chat otrzyma dane wpisywane przez użytkowników w oknie w formacie JSON oraz zdarzenie interakcji, gdzie:

• EventType to CARD_CLICKED.
• DialogEventType ma wartość SUBMIT_DIALOG (tylko w przypadku okien).

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

Aplikacja może uzyskać dostęp do pierwszej wartości wskazanej przez użytkownika w lokalizacji event.common.formInputs.NAME.stringInputs.value[0], gdzie NAME to pole name widżetu TextInput.

Jeśli Twoja aplikacja do obsługi czatu została stworzona przy użyciu Apps Script, zastosuj parametr event.common.formInputs.NAME[""].stringInputs.value[0].

Odbieranie danych z kart

Gdy użytkownik wpisze dane w wiadomości na karcie, aplikacja Google Chat otrzyma zdarzenie interakcji z Google Chat, takie jak:

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

Gdy użytkownik przesyła dane w oknie, aplikacja do obsługi czatu otrzyma inne zdarzenie interakcji z aplikacją Google Chat, takie jak:

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

Reaguj na dane zebrane z wiadomości karty lub okna dialogowego

Po otrzymaniu danych z komunikatu na karcie lub w oknie aplikacja Google Chat odpowiada, potwierdzając odbiór odbioru lub zwracając błąd. W obu tych przypadkach następuje zwrócenie ActionResponse:

• Aby potwierdzić odbiór, wyślij odpowiedź z parametrem ActionResponse zawierającym "actionStatus": "OK".
• Aby zwrócić błąd, w odpowiedzi użyj parametru ActionResponse zawierającego "actionStatus": "ERROR MESSAGE".

Przykład

W tym przykładzie sprawdzamy obecność wartości name. Jeśli go nie ma, 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

Ten przykład wysyła wiadomość dotyczącą karty, zwracając kod card JSON. Możesz też użyć usługi kart 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, interfejs czatu wyświetli komunikat „Coś poszło nie tak” lub „Nie udało się przetworzyć Twojej prośby”. Czasami w interfejsie Google Chat nie pojawia się żaden komunikat o błędzie, ale aplikacja lub karta Google Chat zwraca nieoczekiwany wynik, na przykład komunikat na karcie może się nie pojawić.

Mimo że komunikat o błędzie może nie wyświetlać 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 logowania błędów w aplikacjach do obsługi czatu. Informacje o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z Google Chat i ich naprawianie.