پردازش اطلاعات وارد شده توسط کاربران

این راهنما نحوه دریافت و خواندن اطلاعاتی را که کاربران در پیام‌ها و گفتگوهای کارت وارد می‌کنند، توضیح می‌دهد. کاربران می‌توانند داده‌هایی را وارد کنند که برنامه‌های گپ دریافت می‌کنند، می‌خوانند و به آنها پاسخ می‌دهند. ابزارک هایی که به کاربران اجازه می دهند اطلاعات را وارد کنند عبارتند از:

  • TextInput برای ورود متن به شکل آزاد که از پیشنهادات نیز پشتیبانی می کند.
  • SelectionInput برای آیتم ها و منوهای فهرست، مانند چک باکس ها، دکمه های رادیویی و منوهای کشویی.
  • DateTimePicker برای ورودی های تاریخ و زمان.


طراحی و پیش نمایش کارت ها با Card Builder.

کارت ساز را باز کنید

دریافت داده‌های ورودی از کاربران به برنامه‌های چت اجازه می‌دهد کارهایی مانند موارد زیر را انجام دهند:

  • موارد خدمات مشتری را به روز کنید.
  • سفارشات کاری ایجاد کنید.
  • احراز هویت با خدمات وب

نحوه دریافت داده ها

یک برنامه چت اطلاعات را به عنوان یک گفتگو یا پیام کارت به کاربر ارائه می دهد. در این مثال، یک دیالوگ از کاربر می‌خواهد که اطلاعات مربوط به یک مخاطب را با استفاده از ابزارک‌های TextInput و SelectionInput وارد کند:

دیالوگی شامل انواع ویجت های مختلف.

پس از اتمام، برنامه Chat داده‌هایی را که کاربران در کادر گفتگو وارد کرده‌اند در قالب JSON و یک رویداد تعاملی دریافت می‌کند که در آن:

برای دریافت اطلاعات در مورد آنچه کاربران وارد کرده‌اند، از قسمت Event.common.formInputs در بارگذاری رویداد استفاده کنید. فیلد formInputs نقشه‌ای است که در آن کلیدها شناسه‌های رشته‌ای هستند که به هر ویجت اختصاص داده می‌شوند و مقادیر ورودی کاربر را برای هر ویجت نشان می‌دهند. اشیاء مختلف انواع مختلف داده ورودی را نشان می دهند. برای مثال، Event.common.formInputs.stringInputs ورودی های رشته را نشان می دهد.

برنامه شما می تواند به اولین مقدار وارد شده توسط کاربر در event.common.formInputs. NAME .stringInputs.value[0] ، که در آن NAME فیلد name یک ویجت TextInput است.

دریافت اطلاعات از کارت

وقتی کاربر داده‌ها را در پیام کارت وارد می‌کند، برنامه Chat شما یک رویداد تعامل برنامه Chat را دریافت می‌کند، مانند مثال زیر:

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

دریافت اطلاعات از دیالوگ ها

وقتی یک کاربر داده‌ها را در یک گفتگو ارسال می‌کند، برنامه Chat شما رویداد تعامل دیگری با برنامه Chat را دریافت می‌کند، مانند مثال زیر:

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

به داده های جمع آوری شده از پیام کارت یا گفتگو پاسخ دهید

پس از دریافت داده‌ها از یک پیام کارت یا گفتگو، برنامه Chat با تأیید دریافت یا با برگرداندن یک خطا پاسخ می‌دهد، که هر دو با بازگرداندن ActionResponse انجام می‌شوند:

  • برای تأیید دریافت موفق، با یک پارامتر ActionResponse که دارای "actionStatus": "OK" .
  • برای برگرداندن یک خطا، با یک پارامتر ActionResponse که دارای "actionStatus": " ERROR MESSAGE " .

مثال

مثال زیر وجود یک مقدار name را بررسی می کند. در صورت عدم وجود، برنامه یک خطا برمی‌گرداند. در صورت وجود، برنامه دریافت داده های فرم را تأیید می کند و گفتگو را می بندد.

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"
        }
      }
    });
  }
}

اسکریپت برنامه ها

/**
 * 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"
        }
      }
    };
  }
}

پایتون

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

عیب یابی

وقتی یک برنامه یا کارت Google Chat خطایی را برمی‌گرداند، رابط Chat پیامی را نشان می‌دهد که می‌گوید «مشکلی پیش آمده است». یا "نمی توان به درخواست شما رسیدگی کرد." گاهی اوقات Chat UI هیچ پیام خطایی را نمایش نمی دهد، اما برنامه یا کارت Chat نتیجه غیرمنتظره ای ایجاد می کند. برای مثال، ممکن است پیام کارت ظاهر نشود.

اگرچه ممکن است پیام خطا در رابط کاربری گپ نمایش داده نشود، پیام‌های خطای توصیفی و داده‌های گزارش در دسترس هستند تا به شما کمک کنند هنگام فعال بودن ثبت خطا برای برنامه‌های گپ، خطاها را برطرف کنید. برای راهنمایی برای مشاهده، اشکال‌زدایی و رفع خطاها، به عیب‌یابی و رفع خطاهای Google Chat مراجعه کنید.