تلقّي التفاعلات مع تطبيق Google Chat والردّ عليها

توضّح هذه الصفحة كيف يمكن لتطبيق Google Chat تلقّي تفاعلات المستخدمين والاستجابة لها، والتي تُعرَف أيضًا باسم أحداث التفاعل مع تطبيق Google Chat.

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

على سبيل المثال، تستخدم تطبيقات Chat أحداث التفاعل لتنفيذ أي مما يلي:

مثال على حدث تفاعل	الردّ النموذجي من تطبيق Chat
يستدعي المستخدم تطبيق Chat من خلال الإشارة إليه باستخدام علامة @ أو استخدام أمر شرطة مائلة.	يعالج تطبيق Chat ما تقوله الرسالة لإنشاء رسالة. على سبيل المثال، يردّ تطبيق Chat على الأمر /about برسالة توضّح المهام التي يمكن أن ينفّذها تطبيق Chat.
يضيف مستخدم تطبيق Chat إلى مساحة.	يرسل تطبيق Chat رسالة إعداد توضّح وظيفة التطبيق وكيفية تفاعل المستخدمين في المساحة معه.
يزيل المستخدم تطبيق Chat من مساحة.	يزيل تطبيق Chat أي إشعارات واردة تم ضبطها للمساحة (مثل حذف الرد التلقائي على الويب) ويمحو أي وحدة تخزين داخلية.
ينقر المستخدم على زر في بطاقة أو مربّع حوار مُرسَل من تطبيق Chat.	أما تطبيق Chat، فيعالج ويخزّن أي بيانات أرسلها المستخدم، أو يعرض بطاقة أو مربّع حوار آخر.

لكل نوع من أنواع تفاعل المستخدم، يرسل Google Chat نوعًا مختلفًا من أحداث التفاعل. على سبيل المثال، يستخدم Google Chat نوع الحدث MESSAGE لأي تفاعل يستدعي المستخدم تطبيق Chat في رسالة. لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة أنواع أحداث التفاعل مع تطبيق Google Chat.

توضّح هذه الصفحة كيفية تنفيذ ما يلي:

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

تلقّي أحداث التفاعل مع تطبيقات Chat

يوضّح هذا القسم طريقة تلقّي أحداث التفاعل ومعالجتها في تطبيق Chat.

ضبط تطبيق Chat لتلقّي أحداث التفاعل

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

إذا كنت قد أنشأت تطبيق Chat تفاعليًا، عليك إعداد Google Chat API لكي يتمكّن Google Chat من إرسال أحداث التفاعل إليك:

1. في Google Cloud Console، افتح صفحة Google Chat API:

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

2. انقر على علامة التبويب الإعداد.
3. في قسم الميزات التفاعلية، انقر على زرّ الإيقاف/التفعيل تفعيل الميزات التفاعلية.
4. في الوظائف، ضع علامة في أحد مربّعَي الاختيار التاليين أو كليهما:
   1. تلقّي رسائل بين شخصَين: يسمح هذا الخيار للمستخدمين بالتفاعل مع تطبيق Chat في مساحات الرسائل المباشرة. يتلقّى تطبيق Chat أحداث التفاعل في أي وقت يرسل فيه مستخدم رسالة في مساحة الرسائل المباشرة.
   2. الانضمام إلى المساحات والمحادثات الجماعية: يسمح هذا الخيار للمستخدمين بإضافة تطبيقك على Chat وإزالته إلى المساحات التي تضم أكثر من مستخدم واحد. يتلقّى تطبيق Chat أحداث التفاعل كلّما تمت إضافته أو إزالته من مساحة، ومتى أشار المستخدمون باستخدام الرمز @أو استخدموا أمرًا بشرطة مائلة في المساحة.
5. في إعدادات الربط، حدِّد المكان الذي يرسل فيه Google Chat أحداث التفاعل مع تطبيق Chat.
6. اختياري: في الأوامر التي تبدأ بشرطة مائلة، أضِف إعدادًا واحدًا أو أكثر من الأوامر التي تبدأ بشرطة مائلة. لمزيد من المعلومات، يُرجى الاطّلاع على إعداد الأوامر التي تبدأ بشرطة مائلة.
7. اختياري: في معاينات الروابط، أضِف نمطًا واحدًا أو أكثر من أنماط عناوين URL التي يعاينها تطبيق Chat، واضبطه. لمزيد من المعلومات، يُرجى الاطّلاع على روابط المعاينة.
8. انقر على حفظ.

تم ضبط تطبيق Chat الآن لتلقّي أحداث التفاعل من Google Chat.

مصادقة الطلبات من Google Chat

بالنسبة إلى التطبيقات المستنِدة إلى نقاط نهاية HTTP، يوضّح هذا القسم طريقة التحقّق من أنّ الطلبات إلى نقطة النهاية واردة من Google Chat.

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

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

السلسلة AbCdEf123456 في المثال أعلاه هي الرمز المميّز لتفويض الحامل. هذا رمز مميّز للتشفير تنتجه Google. يمكنك التحقق من رمز الحامل المميز باستخدام مكتبة برامج Google API مفتوحة المصدر:

• Java: https://github.com/google/google-api-java-client
• Python: https://github.com/google/google-api-python-client
• .NET: https://github.com/google/google-api-dotnet-client

بالنسبة إلى الرموز المميزة للحامل التي تم إرسالها في طلبات Google Chat، تكون جهة الإصدار هي [e-mail]، ويتم ضبط الحقل audience على رقم مشروع Google Cloud الذي استخدمته لإنشاء تطبيق Chat. على سبيل المثال، إذا كان رقم مشروع Google Cloud لتطبيق Chat هو 1234567890، يصبح الحقل audience في رمز الحامل المميز 1234567890.

إذا لم يتم إثبات ملكية الرمز المميّز لتطبيق Chat، من المفترض أن تستجيب الخدمة للطلب من خلال رمز استجابة HTTPS 401 (Unauthorized).

Java

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Collections;

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
import com.google.api.client.googleapis.auth.oauth2.GooglePublicKeysManager;
import com.google.api.client.http.apache.ApacheHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;

/** Tool for verifying JWT Tokens for Apps in Google Chat. */
public class JWTVerify {
  // Bearer Tokens received by apps will always specify this issuer.
  static String CHAT_ISSUER = "[e-mail]";

  // Url to obtain the public certificate for the issuer.
  static String PUBLIC_CERT_URL_PREFIX =
      "https://www.googleapis.com/service_accounts/v1/metadata/x509/";

  // Intended audience of the token, which is the project number of the app.
  static String AUDIENCE = "1234567890";

  // Get this value from the request's Authorization HTTPS header.
  // For example, for "Authorization: Bearer AbCdEf123456" use "AbCdEf123456"
  static String BEARER_TOKEN = "AbCdEf123456";

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    JsonFactory factory = new JacksonFactory();

    GooglePublicKeysManager.Builder keyManagerBuilder =
        new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory);

    String certUrl = PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER;
    keyManagerBuilder.setPublicCertsEncodedUrl(certUrl);

    GoogleIdTokenVerifier.Builder verifierBuilder =
        new GoogleIdTokenVerifier.Builder(keyManagerBuilder.build());
    verifierBuilder.setIssuer(CHAT_ISSUER);
    GoogleIdTokenVerifier verifier = verifierBuilder.build();

    GoogleIdToken idToken = GoogleIdToken.parse(factory, BEARER_TOKEN);
    if (idToken == null) {
      System.out.println("Token cannot be parsed");
      System.exit(-1);
    }

    // Verify valid token, signed by CHAT_ISSUER.
    if (!verifier.verify(idToken)
        || !idToken.verifyAudience(Collections.singletonList(AUDIENCE))
        || !idToken.verifyIssuer(CHAT_ISSUER)) {
      System.out.println("Invalid token");
      System.exit(-1);
    }

    // Token originates from Google and is targeted to a specific client.
    System.out.println("The token is valid");
  }
}

Python

import sys

from oauth2client import client

# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = '[e-mail]'

# Url to obtain the public certificate for the issuer.
PUBLIC_CERT_URL_PREFIX = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/'

# Intended audience of the token, which will be the project number of the app.
AUDIENCE = '1234567890'

# Get this value from the request's Authorization HTTPS header.
# For example, for 'Authorization: Bearer AbCdEf123456' use 'AbCdEf123456'.
BEARER_TOKEN = 'AbCdEf123456'

try:
  # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
  token = client.verify_id_token(
      BEARER_TOKEN, AUDIENCE, cert_uri=PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER)

  if token['iss'] != CHAT_ISSUER:
    sys.exit('Invalid issuee')
except:
  sys.exit('Invalid token')

# Token originates from Google and is targeted to a specific client.
print 'The token is valid'

التعامل مع عمليات إعادة محاولة اتصال HTTP على خدمتك

في حال تعذُّر إرسال طلب HTTPS إلى خدمتك (مثل انتهاء مهلة أو عطل مؤقت في الشبكة أو رمز حالة HTTPS ليس من فئة 2xx)، قد يعيد Google Chat تسليم الطلب بضع مرات خلال بضع دقائق (ولكن ذلك ليس مضمونًا). نتيجةً لذلك، قد يتلقّى تطبيق Chat الرسالة نفسها عدة مرات في مواقف معيّنة. إذا اكتمل الطلب بنجاح ولكنّه يعرض حمولة رسالة غير صالحة، لا يُعيد Google Chat محاولة الطلب.

معالجة أحداث التفاعل أو الاستجابة لها

يوضّح هذا القسم كيف يمكن لتطبيقات Google Chat معالجة أحداث التفاعل والاستجابة لها.

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

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

يوضّح المخطّط التالي كيفية معالجة تطبيق Google Chat لأنواع مختلفة من أحداث التفاعل أو الاستجابة لها عادةً:

الردّ في الوقت الفعلي

تتيح أحداث التفاعل لتطبيقات Chat الرد في الوقت الفعلي أو بشكل متزامن. لا تتطلب الاستجابات المتزامنة مصادقة.

لإنشاء استجابات متزامنة لأحداث التفاعل، اطّلِع على الأدلة التالية:

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

للاستجابة بشكلٍ متزامن، يجب أن يستجيب تطبيق Chat في غضون 30 ثانية، ويجب نشر الردّ في المساحة التي حدث فيها التفاعل. وبخلاف ذلك، يمكن لتطبيق Chat الإجابة بشكل غير متزامن.

الرد بشكل غير متزامن

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

لإنشاء رسالة باستخدام Chat API، راجِع المقالة إنشاء رسالة. للحصول على إرشادات حول استخدام طرق Chat API الإضافية، يُرجى الاطّلاع على نظرة عامة على Chat API.