إنشاء تطبيق Google Chat خلف جدار ناري باستخدام Pub/Sub

توضّح هذه الصفحة كيفية إنشاء تطبيق Chat باستخدام نشر/اشتراك: هذا النوع من بنية تطبيق Chat مفيدة إذا كانت مؤسستك تستخدم جدار حماية، ما قد يمنع Chat من إرسال الرسائل إلى تطبيق Chat، أو إذا كان تطبيق Chat تستخدم واجهة برمجة التطبيقات لفعاليات Google Workspace: ومع ذلك، هندسة معمارية لها القيود التالية بسبب حقيقة أن هذه يمكن لتطبيقات Chat إرسال الرسائل وتلقّيها فقط الرسائل غير المتزامنة:

  • لا يمكن استخدام مربعات الحوار في الرسائل. بدلاً من ذلك، استخدم رسالة البطاقة.
  • لا يمكن تعديل بطاقات فردية باستخدام رد متزامن. بدلاً من ذلك، حدِّث الرسالة بأكملها من خلال استدعاء patch .

يوضح الرسم التخطيطي التالي بنية تطبيق Chat الذي تم إنشاؤه من خلال نشر/اشتراك:

يتم تنفيذ بنية تطبيق Chat من خلال نشر/اشتراك.

في الرسم التخطيطي السابق، يتفاعل أحد المستخدمين مع نشر/اشتراك في ما يلي مصادر المعلومات في تطبيق Chat:

  1. إرسال مستخدم رسالة في Chat إلى تطبيق Chat، سواءً في رسالة مباشرة أو في وقوع حدث في "مساحة Chat" أو حدث التي يشتمِل تطبيق Chat على نشاطها الاشتراك.

  2. يرسل Chat الرسالة إلى موضوع النشر/الاشتراك.

  3. هو خادم تطبيقات، سواء كان نظامًا سحابيًا أو نظامًا داخل الشركة يتضمن منطق تطبيق Chat، ويشترك في موضوع النشر/الاشتراك لتلقي الرسالة من خلال جدار الحماية.

  4. اختياريًا، يمكن لتطبيق Chat استدعاء Chat API لنشر الرسائل بشكل غير متزامن أو تنفيذ إجراءات أخرى العمليات التجارية.

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

Java

إعداد البيئة

قبل استخدام Google APIs، يجب تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيقات واحدة أو أكثر في مشروع واحد على Google Cloud.

إعداد نشر/اشتراك

  1. إنشاء موضوع على خدمة Pub/Sub التي يمكن لـ Chat API إرسال الرسائل إليها ننصحك باستخدام موضوع واحد لكل تطبيق في Chat.

  2. منح Chat الإذن للنشر على الموضوع من خلال تعيين دور النشر/الاشتراك في ما يلي: حساب الخدمة:

    chat-api-push@system.gserviceaccount.com

  3. إنشاء حساب خدمة في تطبيق Chat لمنح الأذونات من خلال نشر/اشتراك يمكنك إجراء محادثة وحفظ ملف المفتاح الخاص في دليل العمل.

  4. إنشاء اشتراك Pull with Hint على الموضوع.

  5. امنح دور المشترك في النشر/الاشتراك في الاشتراك. لحساب الخدمة الذي أنشأته سابقًا

كتابة النص

Java

  1. في واجهة سطر الأوامر، قدِّم بيانات اعتماد حساب الخدمة:

    export GOOGLE_APPLICATION_CREDENTIALS=SERVICE_ACCOUNT_FILE_PATH

  2. في سطر الأوامر، قدِّم رقم تعريف مشروع Google Cloud:

    export PROJECT_ID=PROJECT_ID

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

    export SUBSCRIPTION_ID=SUBSCRIPTION_ID

  4. في دليل العمل، أنشِئ ملفًا باسم "pom.xml".

  5. في ملف pom.xml، الصق الرمز التالي:

    java/pub-sub-app/pom.xml
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.google.chat</groupId>
  <artifactId>pub-sub-app</artifactId>
  <version>0.1.0</version>

  <name>pub-sub-app-java</name>

  <properties>
    <maven.compiler.release>21</maven.compiler.release>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>

  <dependencies>
    <!-- Google Chat GAPIC library -->
    <dependency>
      <groupId>com.google.api.grpc</groupId>
      <artifactId>proto-google-cloud-chat-v1</artifactId>
      <version>0.8.0</version>
    </dependency>
    <dependency>
      <groupId>com.google.api</groupId>
      <artifactId>gax</artifactId>
      <version>2.48.1</version>
    </dependency>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>google-cloud-chat</artifactId>
      <version>0.1.0</version>
    </dependency>
    <!-- Google Cloud Pub/Sub library -->
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>google-cloud-pubsub</artifactId>
    <version>1.125.8</version>
    </dependency>
    <!-- JSON utilities -->
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.14.2</version>
    </dependency>
  </dependencies>

</project>

  6. في دليل العمل، أنشِئ بنية الدليل src/main/java.

  7. في دليل src/main/java، أنشِئ ملفًا باسم Main.java.

  8. في Main.java، الصق الرمز التالي:

    java/pub-sub-app/src/main/java/Main.java
    import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.ChatServiceSettings;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.CreateMessageRequest.MessageReplyOption;
import com.google.chat.v1.Message;
import com.google.chat.v1.Thread;
import com.google.cloud.pubsub.v1.AckReplyConsumer;
import com.google.cloud.pubsub.v1.MessageReceiver;
import com.google.cloud.pubsub.v1.Subscriber;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.PubsubMessage;
import java.io.FileInputStream;
import java.util.Collections;

public class Main {

  public static final String PROJECT_ID_ENV_PROPERTY = "PROJECT_ID";
  public static final String SUBSCRIPTION_ID_ENV_PROPERTY = "SUBSCRIPTION_ID";
  public static final String CREDENTIALS_PATH_ENV_PROPERTY = "GOOGLE_APPLICATION_CREDENTIALS";

  public static void main(String[] args) throws Exception {
    ProjectSubscriptionName subscriptionName =
        ProjectSubscriptionName.of(
            System.getenv(Main.PROJECT_ID_ENV_PROPERTY),
            System.getenv(Main.SUBSCRIPTION_ID_ENV_PROPERTY));

    // Instantiate app, which implements an asynchronous message receiver.
    EchoApp echoApp = new EchoApp();

    // Create a subscriber for <var>SUBSCRIPTION_ID</var> bound to the message receiver
    final Subscriber subscriber = Subscriber.newBuilder(subscriptionName, echoApp).build();
    System.out.println("Subscriber is listening to events...");
    subscriber.startAsync();

    // Wait for termination
    subscriber.awaitTerminated();
  }
}

/**
 * A demo app which implements {@link MessageReceiver} to receive messages. It simply echoes the
 * incoming messages.
 */
class EchoApp implements MessageReceiver {

  // Path to the private key JSON file of the service account to be used for posting response
  // messages to Google Chat.
  // In this demo, we are using the same service account for authorizing with Cloud Pub/Sub to
  // receive messages and authorizing with Google Chat to post messages. If you are using
  // different service accounts, please set the path to the private key JSON file of the service
  // account used to post messages to Google Chat here.
  private static final String SERVICE_ACCOUNT_KEY_PATH =
      System.getenv(Main.CREDENTIALS_PATH_ENV_PROPERTY);

  // Developer code for Google Chat API scope.
  private static final String GOOGLE_CHAT_API_SCOPE = "https://www.googleapis.com/auth/chat.bot";

  private static final String ADDED_RESPONSE = "Thank you for adding me!";

  ChatServiceClient chatServiceClient;

  EchoApp() throws Exception {
    GoogleCredentials credential =
        GoogleCredentials.fromStream(new FileInputStream(SERVICE_ACCOUNT_KEY_PATH))
            .createScoped(Collections.singleton(GOOGLE_CHAT_API_SCOPE));

    // Create the ChatServiceSettings with the app credentials
    ChatServiceSettings chatServiceSettings =
        ChatServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Set the Chat service client
    chatServiceClient = ChatServiceClient.create(chatServiceSettings);
  }

  // Called when a message is received by the subscriber.
  @Override
  public void receiveMessage(PubsubMessage pubsubMessage, AckReplyConsumer consumer) {
    System.out.println("Id : " + pubsubMessage.getMessageId());
    // Handle incoming message, then ack/nack the received message
    try {
      ObjectMapper mapper = new ObjectMapper();
      JsonNode dataJson = mapper.readTree(pubsubMessage.getData().toStringUtf8());
      System.out.println("Data : " + dataJson.toString());
      handle(dataJson);
      consumer.ack();
    } catch (Exception e) {
      System.out.println(e);
      consumer.nack();
    }
  }

  // Send message to Google Chat based on the type of event.
  public void handle(JsonNode eventJson) throws Exception {
    CreateMessageRequest createMessageRequest;
    switch (eventJson.get("type").asText()) {
      case "ADDED_TO_SPACE":
        // An app can also be added to a space by @mentioning it in a message. In that case, we fall
        // through to the MESSAGE case and let the app respond. If the app was added using the
        // invite flow, we just post a thank you message in the space.
        if (!eventJson.has("message")) {
          createMessageRequest =
              CreateMessageRequest.newBuilder()
                  .setParent(eventJson.get("space").get("name").asText())
                  .setMessage(Message.newBuilder().setText(ADDED_RESPONSE).build())
                  .build();
          break;
        }
      case "MESSAGE":
        // In case of message, post the response in the same thread.
        createMessageRequest =
            CreateMessageRequest.newBuilder()
                .setParent(eventJson.get("space").get("name").asText())
                .setMessageReplyOption(MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD)
                .setMessage(
                    Message.newBuilder()
                        .setText(
                            "You said: `" + eventJson.get("message").get("text").asText() + "`")
                        .setThread(
                            Thread.newBuilder()
                                .setName(
                                    eventJson.get("message").get("thread").get("name").asText())
                                .build())
                        .build())
                .build();
        break;
      case "REMOVED_FROM_SPACE":
      default:
        // Do nothing
        return;
    }

    // Post the response to Google Chat.
    chatServiceClient.createMessage(createMessageRequest);
  }
}

نشر التطبيق في Chat

  1. في وحدة تحكُّم Google Cloud، انتقِل إلى القائمة &gt; واجهات برمجة التطبيقات و خدمات &gt; واجهات برمجة التطبيقات المفعّلة خدمات &gt; Google Chat API &gt; الإعداد.

    الانتقال إلى "الإعدادات"

  2. اضبط تطبيق Chat للنشر على الإنترنت أو الاشتراك:

    1. في اسم التطبيق، أدخِل Quickstart App.
    2. في عنوان URL للصورة الرمزية، أدخِل https://developers.google.com/chat/images/quickstart-app-avatar.png.
    3. في الوصف، أدخِل Quickstart app.
    4. ضمن الوظائف، اختَر تلقّي الرسائل بين شخصين والانضمام إلى المساحات والمحادثات الجماعية.
    5. ضمن إعدادات الاتصال، اختَر Cloud Pub/Sub والصِق رمز باسم موضوع النشر/الاشتراك الذي أنشأته في السابق.
    6. ضمن مستوى الرؤية، اختَر إتاحة تطبيق Google Chat هذا لمستخدمين محدّدين ومجموعات محدّدة في نطاقك وأدخِل عنوان بريدك الإلكتروني.
    7. ضمن السجلات، اختَر تسجيل الأخطاء في التسجيل.

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

أصبح التطبيق جاهزًا لتلقّي الرسائل والردّ عليها على Chat.

تشغيل النص البرمجي

في واجهة سطر الأوامر، انتقِل إلى دليل العمل وشغِّل النص البرمجي:

Java

mvn compile exec:java -Dexec.mainClass=Main

عند تشغيل الرمز، يبدأ التطبيق في الاستماع إلى الرسائل المنشورة. في موضوع النشر/الاشتراك

اختبار تطبيق Chat

لاختبار تطبيق Chat، افتح مساحة رسائل مباشرة تحتوي على تطبيق Chat وإرسال رسالة:

  1. افتح Google Chat باستخدام حساب Google Workspace الذي المقدّمة عندما أضفت نفسك كمختبِر موثوق به.

    الانتقال إلى Google Chat

  2. انقر على رمز محادثة جديدة.
  3. في الحقل إضافة شخص واحد أو أكثر، اكتب اسم تطبيق Chat

  4. اختَر تطبيقك في Chat من النتائج. عميل مباشر يتم فتح رسالة.

  5. في الرسالة المباشرة الجديدة مع التطبيق، اكتب Hello واضغط على. enter

لإضافة مختبِرين موثوق بهم ومعرفة المزيد من المعلومات حول اختبار الميزات التفاعلية، يُرجى الاطّلاع على اختبار الميزات التفاعلية تطبيقات Google Chat

تحديد المشاكل وحلّها

عند تثبيت تطبيق Google Chat أو تعرض card خطأً، تعرض واجهة Chat رسالة مفادها "حدث خطأ". أو "تعذَّرت معالجة طلبك". في بعض الأحيان، لا يمكن واجهة مستخدم Chat لا يعرض أي رسالة خطأ، ولكن يظهر تطبيق Chat أو ينتج عن بطاقة نتيجة غير متوقعة؛ على سبيل المثال، قد لا تظهر رسالة البطاقة موضع الإعلان.

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

تَنظيم

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

  1. في وحدة تحكُّم Google Cloud، انتقِل إلى صفحة إدارة الموارد. (يُرجى النقر.) قائمة الطعام &gt; إدارة الهوية وإمكانية الوصول و المشرف &gt; إدارة الموارد.

    الانتقال إلى "مدير الموارد"

  2. في قائمة المشاريع، اختَر المشروع الذي تريد حذفه ثم انقر على حذف .
  3. في مربّع الحوار، اكتب رقم تعريف المشروع ثم انقر على إيقاف التشغيل لحذفه. للمشروع.