יצירת אפליקציית HTTP של Google Chat באמצעות Cloud Functions

בדף הזה מוסבר איך יוצרים אפליקציית HTTP Chat. יש כמה דרכים שונות להטמיע את הארכיטקטורה הזו. ב-Google Cloud תוכלו להשתמש ב-Cloud Functions, ב-Cloud Run וב-App Engine. במדריך למתחילים תוכלו לכתוב ולפרוס פונקציה של Cloud Functions שבה אפליקציית Chat משתמשת כדי להגיב להודעות של משתמש.

בארכיטקטורה הזו אפשר להגדיר את Chat כך שישתלב עם Google Cloud או עם שרת מקומי באמצעות HTTP, כפי שמוצג בתרשים הבא:

הארכיטקטורה של אפליקציית Chat שמשתמשת בשירות אינטרנט בשרת מקומי.

בתרשים הקודם, משתמש מקיים אינטראקציה עם אפליקציית HTTP Chat מקבל את זרימת המידע הבאה:

  1. משתמש שולח הודעה ב-Chat לאפליקציית Chat, בצ'אט אישי או במרחב משותף ב-Chat.
  2. בקשת HTTP נשלחת לשרת אינטרנט שהוא מערכת בענן או מערכת מקומית שמכילה את הלוגיקה של אפליקציית Chat.
  3. אפשר גם לשלב את הלוגיקה של אפליקציית Chat עם שירותי Google Workspace (כמו יומן ו-Sheets), שירותים אחרים של Google (כמו מפות Google, YouTube ו-Vertex AI) או שירותי אינטרנט אחרים (כמו מערכת לניהול פרויקטים או כלי כרטיסים).
  4. שרת האינטרנט שולח תגובת HTTP בחזרה לשירות של אפליקציית Chat ב-Chat.
  5. התגובה תישלח למשתמש.
  6. אפשר גם להפעיל את אפליקציית Chat ל-Chat API כדי לפרסם הודעות באופן אסינכרוני או לבצע פעולות אחרות.

הארכיטקטורה הזו מאפשרת להשתמש בספריות וברכיבים קיימים שכבר קיימים במערכת, כי אפשר לעצב את אפליקציות Chat בשפות תכנות שונות.

מטרות

  • הגדרת הסביבה.
  • יצירה ופריסה של פונקציה של Cloud Functions.
  • מפרסמים את האפליקציה ב-Chat.
  • בדיקת האפליקציה

דרישות מוקדמות

  • חשבון Google Workspace עם גישה ל-Google Chat בארגון ב-Google Workspace שמאפשר הפעלות לא מאומתות של פונקציות ב-Google Cloud.

הגדרת הסביבה

כדי להשתמש ב-Google APIs, צריך להפעיל אותם בפרויקט ב-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 Functions

יוצרים ופורסים פונקציה ב-Cloud Functions שיוצרת כרטיס Chat עם השם המוצג ותמונת הדמות של השולח. כשאפליקציית Chat מקבלת הודעה, היא מפעילה את הפונקציה ומגיבה עם הכרטיס.

כך יוצרים ופורסים את הפונקציה של אפליקציית Chat:

Node.js

  1. ב Google Cloud console, נכנסים לדף Cloud Functions:

    כניסה לדף Cloud Functions

    ודאו שבחרתם בפרויקט של אפליקציית Chat.

  2. לוחצים על יצירת פונקציה.

  3. בדף Create function, מגדירים את הפונקציה:

    1. בקטע סביבה, בוחרים באפשרות דור שני.
    2. בקטע שם הפונקציה, מזינים QuickStartChatApp.
    3. בקטע אזור, בוחרים אזור.
    4. בקטע 'אימות', בוחרים באפשרות לאפשר הפעלות לא מאומתות.
    5. לוחצים על הבא.
  4. בקטע Runtime, בוחרים באפשרות Node.js 20.

  5. בקטע קוד מקור, בוחרים באפשרות עורך מוטבע.

  6. בנקודת הכניסה, מוחקים את טקסט ברירת המחדל ומזינים helloChat.

  7. מחליפים את התוכן של index.js בקוד הבא:

    result/avatar-app/index.js (צומת/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. לוחצים על פריסה.

Python

  1. ב Google Cloud console, נכנסים לדף Cloud Functions:

    כניסה לדף Cloud Functions

    ודאו שבחרתם בפרויקט של אפליקציית Chat.

  2. לוחצים על יצירת פונקציה.

  3. בדף Create function, מגדירים את הפונקציה:

    1. בקטע שם הפונקציה, מזינים QuickStartChatApp.
    2. בקטע Trigger type (סוג הטריגר), בוחרים באפשרות HTTP (HTTP).
    3. בקטע 'אימות', בוחרים באפשרות לאפשר הפעלות לא מאומתות.
    4. לוחצים על שמירה.
    5. לוחצים על הבא.
  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. לוחצים על פריסה.

Java

  1. ב Google Cloud console, נכנסים לדף Cloud Functions:

    כניסה לדף Cloud Functions

    ודאו שבחרתם בפרויקט של אפליקציית Chat.

  2. לוחצים על יצירת פונקציה.

  3. בדף Create function, מגדירים את הפונקציה:

    1. בקטע שם הפונקציה, מזינים QuickStartChatApp.
    2. בקטע Trigger type (סוג הטריגר), בוחרים באפשרות HTTP (HTTP).
    3. בקטע 'אימות', בוחרים באפשרות לאפשר הפעלות לא מאומתות.
    4. לוחצים על שמירה.
    5. לוחצים על הבא.
  4. בקטע Runtime, בוחרים באפשרות Java 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. לוחצים על פריסה.

דף הפרטים של Cloud Functions ייפתח והפונקציה תופיע עם שני מדדי התקדמות: אחד ל-build והשני לשירות. כששני מדדי ההתקדמות נעלמים ומוחלפים בסימן וי, הפונקציה נפרסת ומוכנה לשימוש.

פרסום האפליקציה ב-Google Chat

אחרי שפורסים את הפונקציה של Cloud Functions, כדי להפוך אותה לאפליקציית Google Chat:

  1. במסוף Google Cloud, לוחצים על סמל התפריט > Cloud Functions.

    כניסה לדף Cloud Functions

    מוודאים שהפרויקט שבו הפעלתם את Cloud Functions נבחר.

  2. ברשימת הפונקציות, לוחצים על QuickStartChatApp.

  3. בדף הפרטים של הפונקציה, לוחצים על Trigger (טריגרים).

  4. בקטע Trigger URL (כתובת ה-URL של הטריגר), מעתיקים את כתובת ה-URL.

  5. מחפשים את Google Chat API, לוחצים על Google Chat API ואז על ניהול.

    כניסה ל-Chat API

  6. לוחצים על הגדרה ומגדירים את אפליקציית Google Chat:

    1. בקטע שם האפליקציה, מזינים Quickstart App.
    2. בקטע כתובת URL של הדמות, מזינים https://developers.google.com/chat/images/quickstart-app-avatar.png.
    3. בתיאור, מזינים Quickstart app.
    4. בקטע פונקציונליות, בוחרים באפשרות קבלת הודעות אישיות ובאפשרות הצטרפות למרחבים משותפים ולשיחות קבוצתיות.
    5. בקטע Connection settings (הגדרות חיבור), בוחרים באפשרות App URL ומדביקים בתיבה את כתובת ה-URL של הטריגר של הפונקציה של Cloud Functions.
    6. בקטע חשיפה, בחר באפשרות הפוך את אפליקציית Google Chat הזו לזמינה לקבוצות ולאנשים ספציפיים בדומיין שלך, והזן את כתובת האימייל שלך.
    7. בקטע Logs (יומנים), בוחרים באפשרות Log errors to Logging.
  7. לוחצים על שמירה.

אפליקציית Chat מוכנה לקבל הודעות ב-Chat ולהשיב להן.

בדיקה של אפליקציית Chat

כדי לבדוק את אפליקציית Chat, אפשר לשלוח לה הודעה בצ'אט אישי:

  1. פותחים את Google Chat.
  2. כדי לשלוח הודעה בצ'אט אישי לאפליקציה, לוחצים על הסמל 'התחלת צ'אט' ובחלון שמופיע לוחצים על חיפוש אפליקציות.
  3. בתיבת הדו-שיח חיפוש אפליקציות, מחפשים את Quickstart App.
  4. כדי לפתוח צ'אט אישי עם האפליקציה, מאתרים את אפליקציית המדריך למתחילים ולוחצים על הוספה > צ'אט.
  5. כותבים Hello ולוחצים על enter בצ'אט האישי.

התשובה של אפליקציית Chat כוללת הודעת כרטיס עם שם השולח ותמונת הדמות, כפי שמוצג בתמונה הבאה:

אפליקציית Chat מגיבה עם כרטיס שמוצג בו השם המוצג ותמונת הדמות של השולח

כדי להוסיף בודקים נאמנים ולקבל מידע נוסף על בדיקת תכונות אינטראקטיביות, קראו את המאמר בדיקת תכונות אינטראקטיביות לאפליקציות של Google Chat.

פתרון בעיות

כשמוצגת הודעת שגיאה באפליקציה או בכרטיס של Google Chat, מוצגת בממשק של Chat ההודעה "משהו השתבש" או "לא ניתן לעבד את הבקשה שלך". לפעמים לא מוצגת הודעת שגיאה בממשק המשתמש של Chat, אבל קיבלתי תוצאה לא צפויה באפליקציה או בכרטיס של Chat. למשל, יכול להיות שלא תופיע הודעה על כרטיס.

יכול להיות שהודעת השגיאה לא תוצג בממשק המשתמש של Chat, אבל יש הודעות שגיאה תיאוריות ונתוני יומן שיכולים לעזור לכם לתקן שגיאות כשמפעילים רישום שגיאות באפליקציות של Chat. לקבלת עזרה בהצגה, בניפוי באגים ובתיקון שגיאות, אפשר להיעזר במאמר פתרון בעיות ותיקון שגיאות ב-Google Chat.

הסרת המשאבים

על מנת לא לצבור חיובים לחשבון Google Cloud עבור המשאבים שבהם השתמשתם במדריך הזה, מומלץ למחוק את הפרויקט ב-Cloud.

  1. במסוף Google Cloud, עוברים לדף Manage resources. לוחצים על תפריט > IAM ואדמין > ניהול משאבים.

    כניסה למנהל המשאבים

  2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete .
  3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.