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

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

تشرح هذه الصفحة كيفية إنشاء تطبيق HTTP في Chat. وهناك طرق مختلفة لتنفيذ هذه البنية. في Google Cloud، يمكنك استخدام Cloud Functions وCloud Run وApp Engine. في هذا الدليل السريع، يمكنك كتابة ونشر وظيفة Cloud يستخدمها تطبيق 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.
اختبِر التطبيق.

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

حساب Business أو Enterprise Google Workspace لديه إذن بالوصول إلى Google Chat.
مشروع على Google Cloud تم تفعيل الفوترة فيه للتحقّق من أنّه تم تفعيل ميزة الفوترة في مشروع حالي، اطّلِع على مقالة التحقّق من حالة الفوترة في مشاريعك. لإنشاء مشروع وإعداد الفوترة، اطّلِع على مقالة إنشاء مشروع على Google Cloud.

إعداد البيئة

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

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

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

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

أنشئ ونشر دالة Cloud Function لإنشاء بطاقة Chat تتضمّن الاسم المعروض للمُرسِل وصورته الرمزية. عندما يتلقّى تطبيق Chat رسالة، يُنفّذ الدالة ويتلقّى الردّ بالبطاقة.

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

Node.js

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

الانتقال إلى Cloud Functions

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

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

node/avatar-app/index.js

العرض على GitHub

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You need to
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = "";

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

  // Stores the Google Chat event as a variable.
  const event = req.body;

  // Checks for the presence of a slash command in the message.
  if (event.message.slashCommand) {
    // Executes the slash command logic based on its ID.
    // Slash command IDs are set in the Google Chat API configuration.
    switch (event.message.slashCommand.commandId) {
      case ABOUT_COMMAND_ID:
        return res.send({
          privateMessageViewer: event.user,
          text: 'The Avatar app replies to Google Chat messages.'
        });
    }
  }

  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} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, avatarUrl) {
  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: {
          title: `Hello ${displayName}!`,
        },
        sections: [{ widgets: [{
          textParagraph: { text: 'Your avatar picture: ' }
        }, {
          image: { imageUrl: avatarUrl }
        }]}]
      }
    }]
  };
}

انقر على نشر.

Python

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

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

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

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

python/avatar-app/main.py

العرض على GitHub

from typing import Any, Mapping

import flask
import functions_framework

# The ID of the slash command "/about".
# It's not enabled by default, set to the actual ID to enable it. You need to
# use the same ID as set in the Google Chat API configuration.
ABOUT_COMMAND_ID = ""

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Google Cloud Function that handles requests from Google Chat

  Args:
      flask.Request: the request

  Returns:
      Mapping[str, Any]: the response
  """
  if req.method == "GET":
    return "Hello! This function must be called from Google Chat."

  request_json = req.get_json(silent=True)

  # Checks for the presence of a slash command in the message.
  if "slashCommand" in request_json["message"]:
    # Executes the slash command logic based on its ID.
    # Slash command IDs are set in the Google Chat API configuration.
    if request_json["message"]["slashCommand"]["commandId"] == ABOUT_COMMAND_ID:
      return {
        "privateMessageViewer": request_json["user"],
        "text": 'The Avatar app replies to Google Chat messages.'
      }

  display_name = request_json["message"]["sender"]["displayName"]
  avatar = request_json["message"]["sender"]["avatarUrl"]
  response = create_message(name=display_name, image_url=avatar)
  return response


def create_message(name: str, image_url: str) -> Mapping[str, Any]:
  """Google Cloud Function that handles requests from Google Chat

  Args:
      str name: the sender's display name.
      str image_url: the URL for the sender's avatar.

  Returns:
      Mapping[str, Any]: a card with the user's avatar.
  """
  return {
    "text": "Here's your avatar",
    "cardsV2": [{
      "cardId": "avatarCard",
      "card": {
          "name": "Avatar Card",
          "header": { "title": f"Hello {name}!" },
          "sections": [{
            "widgets": [{
              "textParagraph": { "text": "Your avatar picture:" }
            }, {
              "image": { "imageUrl": image_url }
            }]
          }]
      }
    }]
  }

انقر على نشر.

Java

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

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

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

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

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

العرض على GitHub

import java.util.List;

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.api.services.chat.v1.model.User;
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;

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

  // The ID of the slash command "/about".
  // It's not enabled by default, set to the actual ID to enable it. You need to
  // use the same ID as set in the Google Chat API configuration.
  private static final String ABOUT_COMMAND_ID = "";

  @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;
    }

    // Checks for the presence of a slash command in the message.
    if (body.getAsJsonObject("message").has("slashCommand")) {
      // Executes the slash command logic based on its ID.
      // Slash command IDs are set in the Google Chat API configuration.
      JsonObject slashCommand = body.getAsJsonObject("message").getAsJsonObject("slashCommand");
      switch (slashCommand.get("commandId").getAsString()) {
        case ABOUT_COMMAND_ID:
          Message aboutMessage = new Message();
          aboutMessage.setText("The Avatar app replies to Google Chat messages.");
          aboutMessage.setPrivateMessageViewer(new User()
            .setName(body.getAsJsonObject("user").get("name").getAsString()));
          response.getWriter().write(gson.toJson(aboutMessage));
          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) {
    return new Message()
      .setText("Here's your avatar")
      .setCardsV2(List.of(new CardWithId()
        .setCardId("previewLink")
        .setCard(new GoogleAppsCardV1Card()
          .setName("Avatar Card")
          .setHeader(new GoogleAppsCardV1CardHeader()
            .setTitle(String.format("Hello %s!", displayName)))
          .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(
            new GoogleAppsCardV1Widget()
              .setTextParagraph(new GoogleAppsCardV1TextParagraph()
                .setText("Your avatar picture: ")),
            new GoogleAppsCardV1Widget()
              .setImage(new GoogleAppsCardV1Image().setImageUrl(avatarUrl)))))))));
  }
}

استبدل محتوى 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>com.google.chat</groupId>
  <artifactId>avatar-app</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.target>17</maven.compiler.target>
    <maven.compiler.source>17</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-rev20241008-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
في قائمة خدمات Cloud Run، ضَع علامة في مربّع الاختيار بجانب وظيفة الاستقبال . (لا تنقر على الدالة نفسها.)
انقر على الأذونات. يتم فتح لوحة الأذونات.
انقر على إضافة مدير.
في العناصر الرئيسية الجديدة، أدخِل chat@system.gserviceaccount.com.
في اختيار دور، اختَر Cloud Run > Cloud Run Invoker.
انقر على حفظ.

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

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

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

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

تأكَّد من اختيار المشروع الذي فعّلت فيه 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 لنقطة نهاية HTTP والصِق عنوان URL لمشغّل دالة Cloud في المربّع.
6. في Authentication Audience (جمهور المصادقة)، اختَر عنوان URL لنقطة نهاية HTTP.
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 مقابل موارد المستخدَمة في هذا الدليل التعليمي، ننصحك بحذف مشروع Cloud.

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

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

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

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

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

الأهداف

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

إعداد البيئة

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

Node.js

Python

Java

تفويض Google Chat لتشغيل وظيفتك

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

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

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

تَنظيم

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