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

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

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

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

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");
  }
}

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

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

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

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

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

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

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

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

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