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

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

الأمر الذي يبدأ بشرطة مائلة هو طريقة شائعة يستخدِمها المستخدمون للتفاعل مع أحد تطبيقات Chat. وتساعد الأوامر التي تبدأ بشرطة مائلة المستخدمين أيضًا في اكتشاف الميزات الرئيسية لتطبيق Chat واستخدامها.

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

الشكل 1: النافذة التي تظهر عندما يكتب المستخدمون الشرطة المائلة في Google Chat

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

الأوامر التي تبدأ بشرطة مائلة مع الردود الخاصة

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

على سبيل المثال، للاطّلاع على معلومات عن تطبيق Chat الذي يكتشفونه في مساحة، يمكن للمستخدمين استخدام طلبات مثل /about أو /help. لتجنّب إرسال إشعار إلى جميع المستخدمين الآخرين في المساحة، يمكن لتطبيق Chat الردّ بشكل خاص مع تقديم معلومات حول كيفية استخدام تطبيق Chat والحصول على الدعم.

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

ملاحظة: تمّت كتابة نماذج الرموز البرمجية في هذا الدليل لتشغيلها كأحد وظائف Google Cloud لأجل Node.js وPython وJava.

Node.js

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

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

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

Python

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

Java

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

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

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

1. أنشئ اسمًا لأمر الشرطة المائلة.
2. ضبط الأمر "شرطة مائلة" في Google Chat API

أدخِل اسمًا للأمر الذي يبدأ بشرطة مائلة.

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

الشكل 2: اسم أمر يبدأ بشرطة مائلة ووصف له

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

• لتسمية أمر يبدأ بشرطة مائلة:

  • استخدِم كلمات أو عبارات قصيرة ووصفية وقابلة للتنفيذ لجعل الكلمات والتعليمات واضحة وبسيطة للمستخدم. على سبيل المثال، بدلاً من قول /createAReminder، استخدِم /remindMe.
  • إذا كان الأمر يحتوي على أكثر من كلمة واحدة، يمكنك مساعدة المستخدمين في قراءة الأمر من خلال استخدام الأحرف الصغيرة فقط في الكلمة الأولى ثم كتابة الحرف الأول من الكلمات الإضافية بحرف كبير. على سبيل المثال، بدلاً من /updatecontact، استخدِم /updateContact.
  • ننصحك بالتفكير في استخدام اسم فريد أو شائع للأمر. إذا كان الأمر يصف تفاعلًا أو ميزة نموذجية، يمكنك استخدام اسم شائع يتعرّف عليه المستخدمون ويتوقعونه، مثل /settingsأو /feedback. بخلاف ذلك، حاوِل استخدام أسماء أوامر فريدة، لأنّه إذا كان اسم العبارة هو نفسه في تطبيقات Chat الأخرى، على المستخدم التمرير بين الأوامر المتشابهة للعثور على طلبك واستخدامه.

• لوصف الأمر الذي يبدأ بشرطة مائلة:

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

ضبط أمر الشرطة المائلة في Google Chat API

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

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

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

   الانتقال إلى صفحة Google Chat API

2. انقر على الإعداد.

3. ضمن الأوامر التي تبدأ بشرطة مائلة، انقر على إضافة أمر يبدأ بشرطة مائلة.

4. أدخِل اسمًا ورقم تعريف للطلب ووصفًا للطلب:

   1. الاسم: هو الاسم المعروض للطلب، وما يكتبه المستخدمون لتشغيل تطبيقك. يجب أن يبدأ بشرطة مائلة وأن يحتوي على نص فقط، ويمكن أن يحتوي على ما يصل إلى 50 حرفًا.
   2. الوصف: هو النص الذي يصف كيفية استخدام الأمر وتنسيقه. يمكن أن يصل طول الأوصاف إلى 50 حرفًا.
   3. رقم تعريف الأمر: هو رقم يتراوح بين 1 و1000 يستخدمه تطبيق Chat للتعرّف على الأمر الذي يتضمّن الشرطة المائلة وعرض ردّ.

5. اختياري: إذا كنت تريد أن يردّ تطبيق Chat على الطلب من خلال مربّع حوار، ضَع علامة في مربّع الاختيار فتح مربّع حوار.

6. انقر على حفظ.

تم الآن ضبط الأمر الذي يبدأ بشرطة مائلة لتطبيق Chat.

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

لمزيد من الأمثلة، اطّلِع على نماذج تطبيقات Google Chat.

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

يردّ تطبيق Chat بشكل خاص على الأمر المصحوب بشرطة /help لشرح كيفية الحصول على الدعم.

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

Node.js

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

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

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 باستخدام معرّف الأمر الذي تحديده عند ضبط الأمر الذي يبدأ بشرطة مائلة في Chat API. لاختبار هذا الرمز، يُرجى الاطّلاع على مقالة اختبار الميزات التفاعلية لتطبيقات Google Chat.

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

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