تلقّي التفاعلات مع تطبيق 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:

بالنسبة إلى الرموز المميزة للحامل التي تم إرسالها في طلبات Google Chat، تكون جهة الإصدار هي chat@system.gserviceaccount.com ويتم ضبط الحقل audience على رقم مشروع Google Cloud الذي استخدمته لإنشاء تطبيق Chat. على سبيل المثال، إذا كان رقم مشروع 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 = "chat@system.gserviceaccount.com";

  // 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 = 'chat@system.gserviceaccount.com'

# 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 لأنواع مختلفة من أحداث التفاعل أو الاستجابة لها عادةً:

بنية لكيفية معالجة تطبيقات Google Chat لأحداث التفاعل

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

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

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

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

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

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

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