با توابع Cloud یک برنامه HTTP Google Chat بسازید

این صفحه نحوه ایجاد یک برنامه چت HTTP را توضیح می دهد. راه های مختلفی برای پیاده سازی این معماری وجود دارد. در Google Cloud، می‌توانید از Cloud Functions، Cloud Run و App Engine استفاده کنید. در این شروع سریع، یک تابع Cloud را می نویسید و اجرا می کنید که برنامه چت از آن برای پاسخ به پیام کاربر استفاده می کند.

با این معماری، همانطور که در نمودار زیر نشان داده شده است، Chat را برای ادغام با Google Cloud یا سرور داخلی با استفاده از HTTP پیکربندی می‌کنید:

معماری یک برنامه چت با استفاده از یک سرویس وب در یک سرور داخلی.

در نمودار قبل، کاربر در حال تعامل با برنامه چت HTTP دارای جریان اطلاعات زیر است:

  1. کاربر پیامی را در چت به یک برنامه چت، چه در یک پیام مستقیم یا در فضای چت، ارسال می کند.
  2. یک درخواست HTTP به یک سرور وب ارسال می‌شود که یک سیستم ابری یا درون محل است که حاوی منطق برنامه چت است.
  3. در صورت تمایل، منطق برنامه Chat می‌تواند با سرویس‌های Google Workspace (مانند Calendar و Sheets)، سایر سرویس‌های Google (مانند Maps، YouTube، و Vertex AI) یا سایر سرویس‌های وب (مانند سیستم مدیریت پروژه یا ابزار فروش بلیط) یکپارچه شود.
  4. وب سرور یک پاسخ HTTP را به سرویس برنامه Chat در Chat برمی گرداند.
  5. پاسخ به کاربر تحویل داده می شود.
  6. به صورت اختیاری، برنامه چت می‌تواند با Chat API تماس بگیرد تا پیام‌ها را به صورت ناهمزمان ارسال کند یا عملیات دیگری را انجام دهد.

این معماری به شما انعطاف پذیری را برای استفاده از کتابخانه ها و اجزای موجود در سیستم شما ارائه می دهد زیرا این برنامه های چت را می توان با استفاده از زبان های برنامه نویسی مختلف طراحی کرد.

اهداف

  • محیط خود را تنظیم کنید.
  • ایجاد و استقرار یک تابع ابری.
  • برنامه را در چت منتشر کنید.
  • برنامه را تست کنید.

پیش نیازها

  • یک حساب Google Workspace با دسترسی به Google Chat در یک سازمان Google Workspace که به فراخوانی‌های Google Cloud Function احراز هویت نشده اجازه می‌دهد.

محیط را تنظیم کنید

قبل از استفاده از Google API، باید آنها را در پروژه Google Cloud روشن کنید. می‌توانید یک یا چند API را در یک پروژه Google Cloud روشن کنید.
  • در کنسول Google Cloud، Google Chat API، Cloud Build API، Cloud Functions API، Cloud Pub/Sub API، Cloud Logging API، Artifact Registry API، و Cloud Run API را فعال کنید.

    API ها را فعال کنید

ایجاد و استقرار یک تابع ابری

ایجاد و استقرار یک Cloud Function که یک کارت چت با نام نمایشی فرستنده و تصویر آواتار ایجاد می کند. هنگامی که برنامه چت پیامی دریافت می کند، عملکرد را اجرا می کند و با کارت پاسخ می دهد.

برای ایجاد و استقرار عملکرد برای برنامه Chat خود، مراحل زیر را انجام دهید:

Node.js

  1. در کنسول Google Cloud، به صفحه Cloud Functions بروید:

    به Cloud Functions بروید

    مطمئن شوید که پروژه برنامه چت شما انتخاب شده است.

  2. روی Create Function کلیک کنید.

  3. در صفحه ایجاد تابع، تابع خود را تنظیم کنید:

    1. در Environment ، 2nd gen را انتخاب کنید.
    2. در نام تابع ، QuickStartChatApp وارد کنید.
    3. در منطقه ، یک منطقه را انتخاب کنید.
    4. در بخش احراز هویت، اجازه دادن به فراخوان‌های احراز هویت نشده را انتخاب کنید.
    5. روی Next کلیک کنید.
  4. در Runtime ، Node.js 20 را انتخاب کنید.

  5. در کد منبع ، ویرایشگر درون خطی را انتخاب کنید.

  6. در نقطه ورود ، متن پیش فرض را حذف کنید و helloChat وارد کنید.

  7. کد زیر را جایگزین محتوای index.js کنید:

    node/avatar-app/index.js
    /**
     * 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],
          }
        }],
      };
    }

  8. روی Deploy کلیک کنید.

پایتون

  1. در کنسول Google Cloud، به صفحه Cloud Functions بروید:

    به Cloud Functions بروید

    مطمئن شوید که پروژه برنامه چت شما انتخاب شده است.

  2. روی Create Function کلیک کنید.

  3. در صفحه ایجاد تابع، تابع خود را تنظیم کنید:

    1. در نام تابع ، QuickStartChatApp وارد کنید.
    2. در نوع ماشه ، HTTP را انتخاب کنید.
    3. در بخش احراز هویت، اجازه دادن به فراخوان‌های احراز هویت نشده را انتخاب کنید.
    4. روی ذخیره کلیک کنید.
    5. روی Next کلیک کنید.
  4. در Runtime ، Python 3.10 را انتخاب کنید.

  5. در کد منبع ، ویرایشگر درون خطی را انتخاب کنید.

  6. در نقطه ورود ، متن پیش فرض را حذف کنید و hello_chat وارد کنید.

  7. محتوای main.py را با کد زیر جایگزین کنید:

    python/avatar-app/main.py
    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

  8. روی Deploy کلیک کنید.

جاوا

  1. در کنسول Google Cloud، به صفحه Cloud Functions بروید:

    به Cloud Functions بروید

    مطمئن شوید که پروژه برنامه چت شما انتخاب شده است.

  2. روی Create Function کلیک کنید.

  3. در صفحه ایجاد تابع، تابع خود را تنظیم کنید:

    1. در نام تابع ، QuickStartChatApp وارد کنید.
    2. در نوع ماشه ، HTTP را انتخاب کنید.
    3. در بخش احراز هویت، اجازه دادن به فراخوان‌های احراز هویت نشده را انتخاب کنید.
    4. روی ذخیره کلیک کنید.
    5. روی Next کلیک کنید.
  4. در Runtime ، جاوا 11 را انتخاب کنید.

  5. در کد منبع ، ویرایشگر درون خطی را انتخاب کنید.

  6. در نقطه ورود ، متن پیش فرض را حذف کرده و HelloChat وارد کنید.

  7. src/main/java/com/example/Example.java به src/main/java/HelloChat.java تغییر نام دهید.

  8. محتوای HelloChat.java را با کد زیر جایگزین کنید:

    java/avatar-app/src/main/java/HelloChat.java
    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;
      }
    }

  9. کد زیر را جایگزین محتوای pom.xml کنید:

    java/avatar-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>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>

  10. روی Deploy کلیک کنید.

صفحه جزئیات Cloud Functions باز می شود و عملکرد شما با دو نشانگر پیشرفت ظاهر می شود: یکی برای ساخت و دیگری برای سرویس. هنگامی که هر دو نشانگر پیشرفت ناپدید می شوند و با علامت چک جایگزین می شوند، عملکرد شما مستقر و آماده است.

برنامه را در Google Chat منتشر کنید

پس از استقرار عملکرد Cloud، این مراحل را دنبال کنید تا آن را به یک برنامه چت Google تبدیل کنید:

  1. در کنسول Google Cloud، روی منو > عملکردهای ابری کلیک کنید.

    به Cloud Functions بروید

    مطمئن شوید که پروژه ای که برای آن Cloud Functions را فعال کرده اید انتخاب شده باشد.

  2. در لیست توابع، روی QuickStartChatApp کلیک کنید.

  3. در صفحه جزئیات عملکرد، روی Trigger کلیک کنید.

  4. در زیر نشانی اینترنتی ماشه ، URL را کپی کنید.

  5. «Google Chat API» را جستجو کنید و روی Google Chat API کلیک کنید، سپس روی Manage کلیک کنید.

    به Chat API بروید

  6. روی Configuration کلیک کنید و برنامه Google Chat را راه اندازی کنید:

    1. در نام برنامه ، Quickstart App وارد کنید.
    2. در URL آواتار ، https://developers.google.com/chat/images/quickstart-app-avatar.png را وارد کنید.
    3. در توضیحات ، Quickstart app وارد کنید.
    4. در بخش عملکرد ، دریافت پیام های 1:1 و پیوستن به فضاها و مکالمات گروهی را انتخاب کنید.
    5. در قسمت تنظیمات اتصال ، URL برنامه را انتخاب کنید و URL مربوط به راه‌انداز عملکرد Cloud را در کادر قرار دهید.
    6. در قسمت Visibility ، این برنامه Google Chat را برای افراد و گروه‌های خاصی در دامنه خود در دسترس قرار دهید را انتخاب کنید و آدرس ایمیل خود را وارد کنید.
    7. در زیر گزارش‌ها ، Log errors to Logging را انتخاب کنید.
  7. روی ذخیره کلیک کنید.

برنامه چت برای دریافت و پاسخ به پیام ها در چت آماده است.

برنامه چت خود را تست کنید

برای آزمایش برنامه چت خود، یک پیام مستقیم به برنامه ارسال کنید:

  1. Google Chat را باز کنید.
  2. برای ارسال پیام مستقیم به برنامه، روی Start a chat کلیک کنید و در پنجره ظاهر شده، روی Find apps کلیک کنید.
  3. در گفتگوی Find apps ، Quickstart App جستجو کنید.
  4. برای باز کردن یک پیام مستقیم با برنامه، برنامه Quickstart را پیدا کنید و روی Add > Chat کلیک کنید.
  5. در پیام مستقیم Hello تایپ کرده و enter فشار دهید.

پاسخ برنامه چت حاوی یک پیام کارتی است که نام فرستنده و تصویر آواتار را نشان می دهد، همانطور که در تصویر زیر نشان داده شده است:

برنامه چت با کارتی حاوی نام نمایشی فرستنده و تصویر آواتار پاسخ می‌دهد

برای افزودن آزمایش‌کنندگان مورد اعتماد و کسب اطلاعات بیشتر درباره آزمایش ویژگی‌های تعاملی، به تست ویژگی‌های تعاملی برای برنامه‌های گپ Google مراجعه کنید.

عیب یابی خطاها

برای عیب‌یابی و اشکال‌زدایی برنامه چت، به عیب‌یابی و رفع خطاهای برنامه گپ Google مراجعه کنید.