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

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

توضّح هذه الصفحة كيفية إنشاء تطبيق HTTP في Chat. هناك طرق مختلفة لتنفيذ هذه البنية. في Google Cloud، يمكنك استخدام دوال Cloud و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 لنشر الرسائل بشكل غير متزامن أو تنفيذ إجراءات أخرى operations.

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

الأهداف

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

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

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

إعداد البيئة

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

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

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

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

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

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

Node.js

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

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

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

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

node/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 Invoker
انقر على حفظ.

نشر التطبيق على 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 إلى المربع إلى جانب تشغيل دالة السحابة.
6. في جمهور المصادقة، اختر عنوان URL للتطبيق.
7. ضمن مستوى الرؤية، اختَر إتاحة تطبيق Google Chat هذا لمستخدمين محدَّدين مجموعات في نطاقك وأدخِل عنوان بريدك الإلكتروني.
8. ضمن السجلات، اختَر تسجيل الأخطاء في التسجيل.
انقر على حفظ.

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

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

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

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

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

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

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

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

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

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

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

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

تَنظيم

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

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

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

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

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

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

الأهداف

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

إعداد البيئة

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

Node.js

Python

Java

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

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

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

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

تَنظيم

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