تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الردّ على أوامر تطبيق Google Chat

توضّح هذه الصفحة كيفية إعداد الأوامر والردّ عليها بصفتك تطبيق Google Chat.

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

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

أنواع أوامر تطبيق Chat

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

الأوامر التي تبدأ بشرطة مائلة: يرسل المستخدمون الأوامر كرسائل من خلال كتابة شرطة مائلة (/) ثم نص محدّد مسبقًا، مثل /about. يمكن أن تتطلّب تطبيقات المحادثة أيضًا نصًا للوسيطة في الأمر الذي يتضمّن الشرطة المائلة. على سبيل المثال، يمكن أن يتطلّب الأمر الذي يبدأ بشرطة مائلة /search نص وسيطة يُستخدَم لطلب بحث.
الأوامر السريعة: يستخدم المستخدمون الأوامر من خلال فتح القائمة من منطقة الرد في رسالة Chat. لاستخدام أمر، عليهم النقر على إضافة و اختيار أمر من القائمة.

توضّح الصور التالية كيفية اكتشاف المستخدمين لقائمة بالأوامر التي تبدأ بشرطة مائلة والأوامر السريعة:

الشكل 1. يكتشف المستخدمون الأوامر التي تبدأ بشرطة مائلة ويستخدمونها من خلال كتابة شرطة مائلة / في حقل الرد متبوعة باسم الأمر.
الشكل 2. يكتشف المستخدمون الطلبات السريعة ويستخدمونها من قائمة في قسم الرد على رسالة Chat.

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

Node.jsبرمجة تطبيقاتPythonJava

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

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

إعداد الطلب

يوضّح هذا القسم كيفية إكمال الخطوات التالية لإعداد العبارة:

أنشئ اسمًا ووصفًا للطلب.
ضبط الأمر في Google Cloud Console

اسم الأمر ووصفه

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

اسم الأمر الذي يبدأ بشرطة مائلة ووصف له — **الشكل 3**: اسم أمر يبدأ بشرطة مائلة ووصف له.

عند اختيار اسم ووصف للطلب، ننصحك باتّباع الاقتراحات التالية:

لتسمية طلب:

استخدِم كلمات أو عبارات قصيرة ووصفية وقابلة للتنفيذ لجعل الأوامر واضحة لمستخدم التطبيق. على سبيل المثال، بدلاً من الاسم Create a reminder، استخدِم Remind me.
ننصحك باستخدام اسم فريد أو شائع لطلبك. إذا كان الأمر يصف تفاعلًا أو ميزة نموذجية، يمكنك استخدام اسم شائع يتعرّف عليه المستخدمون ويتوقعونه، مثل Settings أو Feedback. بخلاف ذلك، حاوِل استخدام أسماء أوامر فريدة، لأنّه إذا كان اسم الأمر هو نفسه في تطبيقات Chat الأخرى، على المستخدم فلترة الأوامر المشابهة للعثور على الأمر الخاص بك واستخدامه.

لوصف طلب:

يجب أن يكون الوصف قصيرًا وواضحًا حتى يعرف المستخدمون ما يمكن توقّعه عند استخدام الأمر.
يُرجى إبلاغ المستخدمين إذا كانت هناك أي متطلبات تنسيق للأمر. على سبيل المثال، إذا أنشأت طلبًا يتضمّن الشرطة المائلة ويتطلّب نص وسيطة، اضبط الوصف على Remind me to do [something] at [time].
أطلِع المستخدمين على ما إذا كان تطبيق Chat يردّ على جميع المستخدمين في المساحة، أو بشكل خاص على المستخدم الذي يُجري الطلب. على سبيل المثال، بالنسبة إلى الأمر السريع About، يمكنك وصفه على النحو التالي: Learn about this app (Only visible to you).

ضبط الأمر في "وحدة تحكّم Google Cloud"

لإنشاء شرطة مائلة أو أمر سريع، يمكنك تحديد معلومات عن الأمر في إعدادات تطبيق Chat لواجهة برمجة التطبيقات Google Chat API.

لضبط أمر في Google Chat API، أكمِل الخطوات التالية:

في وحدة تحكّم Google Cloud، انقر على رمز القائمة > واجهات برمجة التطبيقات والخدمات > واجهات برمجة التطبيقات والخدمات المفعَّلة > Google Chat API.

الانتقال إلى صفحة Google Chat API
انقر على الإعداد.
ضمن الطلبات، انقر على إضافة طلب.
أدخِل رقم تعريف الأمر واسمه ووصفه ونوعه:
- رقم تعريف الطلب: رقم يتراوح بين 1 و1000 يستخدمه تطبيق Chat للتعرّف على الطلب وvuelto تقديم ردّ.
- الاسم: الاسم المعروض للطلب. يمكن أن تتألف الأسماء من 50 حرفًا بحد أقصى ويمكن أن تتضمّن رموزًا خاصة.
- الوصف: النص الذي يصف ما يفعله الأمر يمكن أن تتألف الأوصاف من 50 حرفًا كحد أقصى ويمكن أن تتضمّن أحرفًا خاصة.
- نوع الأمر: اختَر أمر سريع أو أمر الشرطة المائلة.
- في حال ضبط أمر شرطة مائلة، أدخِل قيمة لحقل اسم الأمر المكوّن من شرطة مائلة لتحديد ما يكتبه المستخدمون لتشغيل الأمر. يجب أن يبدأ بشرطة مائلة وأن يحتوي على نص فقط، ويُسمَح باستخدام ما يصل إلى 50 حرفًا. مثلاً: /remindMe
اختياري: إذا كنت تريد أن يردّ تطبيق Chat على الطلب من خلال مربّع حوار، ضَع علامة في مربّع الاختيار فتح مربّع حوار.
انقر على حفظ.

تم الآن ضبط الأمر لتطبيق Chat.

الردّ على أمر

عندما يستخدم المستخدمون أحد الأوامر، يتلقّى تطبيق Chat حدث تفاعل. تحتوي البيانات الأساسية للحدث على بيانات وصفية تتضمّن تفاصيل عن الأمر الذي تم استدعاؤه (بما في ذلك معرّف الأمر ونوعه)، حتى تتمكّن من عرض ردّ مناسب.

رسالة خاصة لتطبيق
Chat من Cymbal Labs. توضّح الرسالة أنّه تم إنشاء
تطبيق Chat من Cymbal Labs، وتشارك رابطًا
يؤدي إلى المستندات ورابطًا للتواصل مع فريق الدعم. — يردّ تطبيق Chat بشكل خاص على الأمر المصحوب بشرطة `/help` لشرح كيفية الحصول على الدعم.

للردّ على كل نوع من أنواع الأوامر، عليك التعامل مع أنواع الأحداث المختلفة وعناصر البيانات الوصفية في الحمولة الخاصة بالحدث:

نوع الطلب	نوع الحدث	البيانات الوصفية للأوامر
أمر يبدأ بشرطة مائلة	`MESSAGE`	`message.slashCommand` أو `message.annotation.slashCommand`
أمر سريع	`APP_COMMAND`	`appCommandMetadata`

للتعرّف على كيفية الردّ على أمر باستخدام رسالة، اطّلِع على الأقسام التالية.

الردّ على أمر يبدأ بشرطة مائلة

يعرض الرمز البرمجي التالي مثالاً على تطبيق Chat ي replyي إلى الأمر المكوّن من الشرطة المائلة /about. يعالج تطبيق Chat أحداث التفاعل مع MESSAGE، ويرصد ما إذا كان حدث التفاعل يحتوي على معرّف الطلب المطابق، ويعرض رسالة خاصة:

Node.js برمجة تطبيقات Python Java

node/avatar-app/index.js

العرض على GitHub

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

apps-script/avatar-app/avatar-app.gs

العرض على GitHub

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

python/avatar-app/main.py

العرض على GitHub

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

java/avatar-app/src/main/java/AvatarApp.java

العرض على GitHub

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

استبدِل ABOUT_COMMAND_ID بمعرّف الأمر الذي تحديده عند ضبط الأمر في وحدة تحكّم Google Cloud.

الردّ على أمر سريع

يعرض الرمز البرمجي التالي مثالاً على تطبيق Chat الذي يردّ على الأمر السريع مساعدة. يعالج تطبيق Chat أحداث التفاعل مع APP_COMMAND، ويرصد ما إذا كان حدث التفاعل يحتوي على معرّف الطلب المطابق، ويعرض رسالة خاصة:

Node.js برمجة تطبيقات Python Java

node/avatar-app/index.js

العرض على GitHub

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

apps-script/avatar-app/avatar-app.gs

العرض على GitHub

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

python/avatar-app/main.py

العرض على GitHub

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

java/avatar-app/src/main/java/AvatarApp.java

العرض على GitHub

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

استبدِل HELP_COMMAND_ID بمعرّف الأمر الذي تحديده عند ضبط الأمر في وحدة تحكّم Google Cloud.

اختبار الأمر

لاختبار الأمر والرمز، يُرجى الاطّلاع على مقالة اختبار الميزات التفاعلية لتطبيقات Google Chat.

للتعرّف على كيفية اختبار الأمر واستخدامه في واجهة مستخدم Chat، اطّلِع على مقالة استخدام التطبيقات في Google Chat في مستندات مساعدة Google Chat.

الاطّلاع على نماذج تطبيقات Chat التي تستخدم الأوامر
إرسال رسالة
فتح مربّعات حوار تفاعلية

الردّ على أوامر تطبيق Google Chat

أنواع أوامر تطبيق Chat

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

إعداد الطلب

اسم الأمر ووصفه

لتسمية طلب:

لوصف طلب:

ضبط الأمر في "وحدة تحكّم Google Cloud"

الردّ على أمر

الردّ على أمر يبدأ بشرطة مائلة

الردّ على أمر سريع

اختبار الأمر

مواضيع ذات صلة