تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إنشاء تطبيق Google Chat لبروتوكول HTTP باستخدام دوال السحابة

تشرح هذه الصفحة كيفية إنشاء تطبيق HTTP في Chat. وهناك طرق مختلفة لتنفيذ هذه البنية. في Google Cloud، يمكنك استخدام Cloud Functions وCloud Run وApp Engine. في مرحلة البدء السريع هذه، ستكتب وتنشر وظيفة في السحابة الإلكترونية يستخدمها تطبيق Chat للردّ على رسالة المستخدم.

من خلال هذه البنية، يمكنك ضبط Chat ليتم دمجه مع Google Cloud أو خادم محلي باستخدام HTTP على النحو الموضّح في المخطّط البياني التالي:

بنية تطبيق Chat باستخدام خدمة ويب في خادم داخل المؤسسة

في المخطّط السابق، تظهر المعلومات التالية لدى المستخدم الذي يتفاعل مع تطبيق HTTP Chat:

يرسل المستخدم رسالة في Chat إلى تطبيق Chat، إما في رسالة مباشرة أو في مساحة Chat.
يتم إرسال طلب HTTP إلى خادم ويب يكون إما على السحابة الإلكترونية أو نظام داخل الشركة يحتوي على منطق تطبيق Chat.
يمكن أن يتكامل منطق التطبيق مع Chat اختياريًا مع خدمات Google Workspace (مثل "تقويم Google" و"جداول بيانات Google") أو خدمات Google الأخرى (مثل "خرائط Google" وYouTube وVertex AI) أو خدمات الويب الأخرى (مثل نظام إدارة المشاريع أو أداة إصدار التذاكر).
يرسل خادم الويب استجابة HTTP مرة أخرى إلى خدمة تطبيق Chat في Chat.
يتم تسليم الرد إلى المستخدم.
اختياريًا، يمكن لتطبيق Chat استدعاء Chat API لنشر الرسائل بشكل غير متزامن أو تنفيذ عمليات أخرى.

وتمنحك هذه البنية المرونة لاستخدام المكتبات والمكوّنات الحالية المتوفّرة في نظامك لأنّه يمكن تصميم تطبيقات Chat هذه باستخدام لغات برمجة مختلفة.

الأهداف

إعداد البيئة.
إنشاء دالة Cloud ونشرها
انشر التطبيق في Chat.
اختبِر التطبيق.

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

حساب على Google Workspace يمكنه الوصول إلى Google Chat ووظائف Google Cloud.
مشروع على Google Cloud:
تأكَّد من تفعيل الفوترة لمشروعك على Google Cloud. تعرّف على كيفية التحقّق من حالة الفوترة لمشاريعك.

إعداد البيئة

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

في Google Cloud Console، فعِّل واجهة برمجة التطبيقات Google Chat وCloud Build API وCloud Functions API وCloud Pub/Sub API وCloud Logging API وواجهة برمجة التطبيقات Artifact Registry API وCloud Run API.

تفعيل واجهات برمجة التطبيقات

إنشاء دالة Cloud ونشرها

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

لإنشاء الوظيفة وتفعيلها في تطبيق Chat، يُرجى إكمال الخطوات التالية:

Node.js

في وحدة التحكّم في Google Cloud، انتقِل إلى صفحة "وظائف السحابة الإلكترونية":

الانتقال إلى وظائف السحابة الإلكترونية

تأكَّد من اختيار مشروع تطبيق Chat.
انقر على إنشاء دالة.
في صفحة "إنشاء دالة"، قم بإعداد الدالة الخاصة بك:
1. في البيئة، اختَر الجيل الثاني.
2. في اسم الدالة، أدخِل QuickStartChatApp.
3. في المنطقة، اختَر منطقة.
4. ضمن "المصادقة"، اختَر طلب المصادقة.
5. انقر على التالي.
في وقت التشغيل، اختَر أحدث إصدار من Node.js.
في رمز المصدر، اختَر المحرِّر المضمّن.
في نقطة الإدخال، احذف النص التلقائي وأدخِل helloChat.

استبدل محتوى index.js بالرمز التالي:

العقدة/avatar-app/index.js

عرض على GitHub

/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat room.
 *
 * @param {Object} req Request sent from Google Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Google Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

انقر على نشر.

Python

في وحدة التحكّم في Google Cloud، انتقِل إلى صفحة "وظائف السحابة الإلكترونية":

الانتقال إلى وظائف السحابة الإلكترونية

تأكَّد من اختيار مشروع تطبيق Chat.
انقر على إنشاء دالة.
في صفحة "إنشاء دالة"، قم بإعداد الدالة الخاصة بك:
1. في البيئة، اختَر الجيل الثاني.
2. في اسم الدالة، أدخِل QuickStartChatApp.
3. في المنطقة، اختَر منطقة.
4. ضمن "المصادقة"، اختَر طلب المصادقة.
5. انقر على التالي.
في وقت التشغيل، اختَر أحدث إصدار من Python.
في رمز المصدر، اختَر المحرِّر المضمّن.
في نقطة الإدخال، احذف النص التلقائي وأدخِل hello_chat.

استبدل محتوى main.py بالرمز التالي:

python/avatar-app/main.py

عرض على GitHub

from typing import Any, Mapping

import flask
import functions_framework


# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request) -> Mapping[str, Any]:
  if req.method == "GET":
    return "Hello! This function must be called from Google Chat."

  request_json = req.get_json(silent=True)

  display_name = request_json["message"]["sender"]["displayName"]
  avatar = request_json["message"]["sender"]["avatarUrl"]

  response = create_message(name=display_name, image_url=avatar)

  return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
  avatar_image_widget = {"image": {"imageUrl": image_url}}
  avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
  avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

  header = {"title": f"Hello {name}!"}

  cards = {
      "text": "Here's your avatar",
      "cardsV2": [
          {
              "cardId": "avatarCard",
              "card": {
                  "name": "Avatar Card",
                  "header": header,
                  "sections": [avatar_section],
              },
          }
      ]
  }

  return cards

انقر على نشر.

Java

في وحدة التحكّم في Google Cloud، انتقِل إلى صفحة "وظائف السحابة الإلكترونية":

الانتقال إلى وظائف السحابة الإلكترونية

تأكَّد من اختيار مشروع تطبيق Chat.
انقر على إنشاء دالة.
في صفحة "إنشاء دالة"، قم بإعداد الدالة الخاصة بك:
1. في البيئة، اختَر الجيل الثاني.
2. في اسم الدالة، أدخِل QuickStartChatApp.
3. في المنطقة، اختَر منطقة.
4. ضمن "المصادقة"، اختَر طلب المصادقة.
5. انقر على التالي.
في وقت التشغيل، اختَر أحدث إصدار من Java.
في رمز المصدر، اختَر المحرِّر المضمّن.
في نقطة الإدخال، احذف النص التلقائي وأدخِل HelloChat.
إعادة تسمية "src/main/java/com/example/Example.java" إلى src/main/java/HelloChat.java

استبدل محتوى HelloChat.java بالرمز التالي:

java/avatar-app/src/main/java/HelloChat.java

عرض على GitHub

import com.google.api.services.chat.v1.model.CardWithId;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Card;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1CardHeader;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Image;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Section;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1TextParagraph;
import com.google.api.services.chat.v1.model.GoogleAppsCardV1Widget;
import com.google.api.services.chat.v1.model.Message;
import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import java.util.List;

public class HelloChat implements HttpFunction {
  private static final Gson gson = new Gson();

  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject body = gson.fromJson(request.getReader(), JsonObject.class);

    if (request.getMethod().equals("GET") || !body.has("message")) {
      response.getWriter().write("Hello! This function must be called from Google Chat.");
      return;
    }

    JsonObject sender = body.getAsJsonObject("message").getAsJsonObject("sender");
    String displayName = sender.has("displayName") ? sender.get("displayName").getAsString() : "";
    String avatarUrl = sender.has("avatarUrl") ? sender.get("avatarUrl").getAsString() : "";
    Message message = createMessage(displayName, avatarUrl);

    response.getWriter().write(gson.toJson(message));
  }

  Message createMessage(String displayName, String avatarUrl) {
    GoogleAppsCardV1CardHeader cardHeader = new GoogleAppsCardV1CardHeader();
    cardHeader.setTitle(String.format("Hello %s!", displayName));

    GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
    textParagraph.setText("Your avatar picture: ");

    GoogleAppsCardV1Widget avatarWidget = new GoogleAppsCardV1Widget();
    avatarWidget.setTextParagraph(textParagraph);

    GoogleAppsCardV1Image image = new GoogleAppsCardV1Image();
    image.setImageUrl(avatarUrl);

    GoogleAppsCardV1Widget avatarImageWidget = new GoogleAppsCardV1Widget();
    avatarImageWidget.setImage(image);

    GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
    section.setWidgets(List.of(avatarWidget, avatarImageWidget));

    GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
    card.setName("Avatar Card");
    card.setHeader(cardHeader);
    card.setSections(List.of(section));

    CardWithId cardWithId = new CardWithId();
    cardWithId.setCardId("previewLink");
    cardWithId.setCard(card);

    Message message = new Message();
    message.setText("Here's your avatar");
    message.setCardsV2(List.of(cardWithId));

    return message;
  }
}

استبدل محتوى pom.xml بالرمز التالي:

java/avatar-app/pom.xml

عرض على GitHub

<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>cloudfunctions</groupId>
  <artifactId>http-function</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.target>11</maven.compiler.target>
    <maven.compiler.source>11</maven.compiler.source>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.0.1</version>
    </dependency>

    <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.9.1</version>
    </dependency>

    <!-- https://mvnrepository.com/artifact/com.google.apis/google-api-services-chat -->
    <dependency>
      <groupId>com.google.apis</groupId>
      <artifactId>google-api-services-chat</artifactId>
      <version>v1-rev20230115-2.0.0</version>
    </dependency>
  </dependencies>

  <!-- Required for Java 11 functions in the inline editor -->
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.8.1</version>
        <configuration>
          <excludes>
            <exclude>.google/</exclude>
          </excludes>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

انقر على نشر.

ستفتح صفحة تفاصيل "وظائف السحابة الإلكترونية"، وتظهر وظيفتك مع مؤشرَين للتقدّم: أحدهما للإصدار والآخر للخدمة. عندما يختفي كلا مؤشري التقدم ويتم استبدالهما بعلامة اختيار، تكون الدالة منشورة وجاهزة.

تفويض Google Chat لاستدعاء الوظيفة

من أجل تفويض Google Chat لاستدعاء الوظيفة، أضِف حساب خدمة Google Chat الذي لديه دور Cloud Run Invoker.

في Google Cloud Console، انتقِل إلى صفحة "تشغيل السحابة الإلكترونية":

الانتقال إلى Cloud Run
في قائمة خدمات تشغيل السحابة الإلكترونية، ضَع علامة في مربّع الاختيار بجانب دالة الاستلام. (لا تنقر على الدالة نفسها.)
انقر على الأذونات. ستظهَر لوحة الأذونات.
انقر على إضافة مدير.
في العناصر الرئيسية الجديدة، أدخِل chat@system.gserviceaccount.com.
في اختيار دور، اختَر تشغيل السحابة الإلكترونية > مُستدعي Cloud Run.
انقر على حفظ.

نشر التطبيق على Google Chat

بعد تفعيل ميزة Cloud Function، اتّبِع الخطوات التالية لتحويلها إلى تطبيق في Google Chat:

في وحدة تحكُّم Google Cloud، انقر على رمز القائمة > دوال السحابة الإلكترونية.

الانتقال إلى وظائف السحابة الإلكترونية

تأكَّد من اختيار المشروع الذي فعَّلت Cloud Functions فيه.
في قائمة الدوال، انقر على QuickStartChatApp.
انقر على علامة التبويب العوامل المشغِّلة.
ضمن HTTPS، انسخ عنوان URL.
ابحث عن Google Chat API وانقر على Google Chat API، ثم انقر على إدارة.

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

تطبيق Chat جاهز لتلقي الرسائل في Chat والرد عليها

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

لاختبار تطبيق Chat، افتح مساحة رسائل مباشرة باستخدام تطبيق Chat وأرسِل رسالة:

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

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

ملاحظة:إذا لم يظهر تطبيق Chat في قائمة النتائج، تأكَّد من تضمين حسابك على Google Workspace في إعدادات إذن الوصول في صفحة إعداد واجهة برمجة تطبيقات Chat في Google Cloud Console.
في الرسالة المباشرة الجديدة مع التطبيق، اكتب Hello واضغط على enter.

يتضمّن ردّ تطبيق Chat رسالة بطاقة تعرض اسم المُرسِل وصورته الرمزية، كما هو موضّح في الصورة التالية:

تطبيق Chat يستجيب من خلال بطاقة تعرض الاسم المعروض الخاص بالمُرسِل وصورته الرمزية

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

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

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

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

تَنظيم

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

تنبيه: ينتج عن حذف المشروع التأثيرات التالية:

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

إذا كنت تخطط لاستكشاف العديد من البرامج التعليمية والبدايات السريعة، فيمكن أن تساعدك إعادة استخدام المشروعات في تجنب تجاوز حدود حصة المشروع.

في وحدة تحكُّم Google Cloud، انتقِل إلى صفحة إدارة الموارد. انقر على القائمة > إدارة الهوية وإمكانية الوصول والمشرف > إدارة الموارد.
الانتقال إلى Resource Manager
في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على حذف .
في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على إيقاف التشغيل لحذف المشروع.

إنشاء تطبيق Google Chat لبروتوكول HTTP باستخدام دوال السحابة

الأهداف

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

إعداد البيئة

إنشاء دالة Cloud ونشرها

Node.js

Python

Java

تفويض Google Chat لاستدعاء الوظيفة

نشر التطبيق على Google Chat

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

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

تَنظيم

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