معلومات المستخدمين التي أدخلوها

يوضِّح هذا الدليل طريقة تلقّي وقراءة المعلومات التي يُدخلها المستخدمون. رسائل البطاقة أو مربعات الحوار يمكن للمستخدمين إدخال البيانات التي تتلقّاها التطبيقات في Chat وتقرأها وتردّ عليها. إليه. تشمل التطبيقات المصغّرة التي تسمح للمستخدمين بإدخال المعلومات ما يلي:

• TextInput لإدخال نص حر الشكل يدعم الاقتراحات أيضًا.
• SelectionInput لعناصر القائمة والقوائم، مثل مربعات الاختيار وأزرار الاختيار والقوائم المنسدلة.
• DateTimePicker لإدخالات التاريخ والوقت.

---

يمكنك استخدام "أداة إنشاء البطاقات" لتصميم رسائل بطاقات JSON ومعاينتها لتطبيقات Chat:

فتح "أداة إنشاء البطاقات"

---

إنّ تلقّي البيانات التي يتم إدخالها من المستخدمين يسمح لتطبيقات Chat بتنفيذ إجراءات، مثل: ما يلي:

• تعديل طلبات الحصول على خدمة العملاء
• إنشاء أوامر العمل.
• المصادقة باستخدام خدمات الويب

المتطلبات الأساسية

ملاحظة: بالنسبة إلى Node.js وPython، تتم كتابة عيّنات التعليمات البرمجية في هذا الدليل لتشغيلها. كوظيفة في Google Cloud.

Node.js

تطبيق Google Chat مفعَّل للميزات التفاعلية لإنشاء تطبيق Chat تفاعليًا باستخدام خدمة HTTP، أكمِل عملية البدء السريع هذه.

برمجة تطبيقات

تطبيق Google Chat مفعَّل للميزات التفاعلية لإنشاء تطبيق Chat التفاعلي في "برمجة تطبيقات Google"، أكمِل البدء السريع هذا.

Python

تطبيق Google Chat مفعَّل للميزات التفاعلية لإنشاء تطبيق Chat تفاعليًا باستخدام خدمة HTTP، أكمِل عملية البدء السريع هذه.

آلية عمل تلقّي البيانات

يقدِّم تطبيق Chat معلومات للمستخدم على شكل مربع حوار أو رسالة بطاقة. في هذا المثال، يطلب مربّع حوار من المستخدم إدخال المعلومات حول جهة اتصال باستخدام TextInput أو SelectionInput التطبيقات المصغّرة:

عند الانتهاء، يتلقّى تطبيق Chat البيانات إدخال مستخدم في مربع الحوار بتنسيق JSON حدث تفاعل عندما:

• EventType CARD_CLICKED.
• DialogEventType يبلغ SUBMIT_DIALOG (لمربعات الحوار فقط).

للحصول على بيانات حول ما أدخله المستخدمون، استخدم Event.common.formInputs في حمولة الحدث. أمّا الحقل formInputs، فهو خريطة تعرض المفاتيح الأرقام التعريفية للسلسلة المخصصة لكل تطبيق مصغّر، وتمثل القيم الإدخال الخاص بالمستخدم لكل تطبيق مصغّر. تمثل الكائنات المختلفة أنواع بيانات إدخال مختلفة. بالنسبة مثال، Event.common.formInputs.stringInputs لتمثيل مدخلات السلسلة.

يمكن لتطبيقك الوصول إلى أول قيمة أدخلها المستخدم على event.common.formInputs.NAME.stringInputs.value[0], حيث NAME هو الحقل name في التطبيق المصغّر TextInput

إذا تم إنشاء تطبيق Chat باستخدام برمجة التطبيقات، استخدام event.common.formInputs.NAME[""].stringInputs.value[0] بدلاً من ذلك.

تلقّي البيانات من البطاقات

عندما يُدخل مستخدم بيانات في رسالة بطاقة، يتلقّى تطبيق 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"
        }
      }
    });
  }
}

برمجة تطبيقات

يرسل هذا المثال رسالة بطاقة من خلال عرض بطاقة JSON. يمكنك أيضًا استخدام صفحة خدمة بطاقة "برمجة تطبيقات Google"

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

تحديد المشاكل وحلّها

عند تثبيت تطبيق Google Chat أو تعرض card خطأً، تعرض واجهة Chat رسالة مفادها "حدث خطأ". أو "تعذَّرت معالجة طلبك". في بعض الأحيان، لا يمكن واجهة مستخدم Chat لا يعرض أي رسالة خطأ، ولكن يظهر تطبيق Chat أو ينتج عن بطاقة نتيجة غير متوقعة؛ على سبيل المثال، قد لا تظهر رسالة البطاقة موضع الإعلان.

على الرغم من أنه قد لا تظهر رسالة الخطأ في واجهة مستخدم Chat، تتوفر رسائل خطأ وصفية وبيانات السجل لمساعدتك في إصلاح الأخطاء عند تفعيل ميزة تسجيل الأخطاء لتطبيقات Chat للحصول على مساعدة في العرض، وتصحيح الأخطاء وإصلاح الأخطاء، فراجع تحديد مشاكل Google Chat وحلّها.