פיתוח אפליקציית HTTP ב-Google Chat

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

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

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

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

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

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

מטרות

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

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

הגדרת הסביבה

לפני שמשתמשים בממשקי 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 Functions

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

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

Node.js

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

    כניסה לדף Cloud Functions

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

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

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

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

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

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

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

    node/avatar-app/index.js
    const functions = require('@google-cloud/functions-framework');
    
    // Command IDs (configure these in Google Chat API)
    const ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
    const HELP_COMMAND_ID = 2; // ID for the "Help" quick command
    
    /**
     * Google Cloud Function that handles HTTP requests from Google Chat.
     *
     * @param {Object} req - The HTTP request object sent from Google Chat.
     * @param {Object} res - The HTTP response object.
     */
    functions.http('avatarApp', (req, res) => {
      const event = req.body;
    
      if (event.appCommandMetadata) {
        handleAppCommands(event, res);
      } else {
        handleRegularMessage(event, res);
      }
    });
    
    /**
     * Handles slash and quick commands.
     *
     * @param {Object} event - The Google Chat event.
     * @param {Object} res - The HTTP response object.
     */
    function handleAppCommands(event, res) {
      const {appCommandId, appCommandType} = event.appCommandMetadata;
    
      switch (appCommandId) {
        case ABOUT_COMMAND_ID:
          return res.send({
            privateMessageViewer: event.user,
            text: 'The Avatar app replies to Google Chat messages.'
          });
        case HELP_COMMAND_ID:
          return res.send({
            privateMessageViewer: event.user,
            text: 'The Avatar app replies to Google Chat messages.'
          });
      }
    }
    
    /**
     * Handles regular messages (not commands).
     *
     * @param {Object} event - The Google Chat event.
     * @param {Object} res - The HTTP response object.
     */
    function handleRegularMessage(event, res) {
      const messageData = createMessage(event.user);
      res.send(messageData);
    }
    
    /**
     * Creates a card message with the user's avatar.
     *
     * @param {Object} user - The user who sent the message.
     * @param {string} user.displayName - The user's display name.
     * @param {string} user.avatarUrl - The URL of the user's avatar.
     * @return {Object} - The card message object.
     */
    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}},
              ],
            }],
          },
        }],
      };
    }

  8. לוחצים על פריסה.

Python

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

    כניסה לדף Cloud Functions

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

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

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

    1. בקטע סביבה, בוחרים באפשרות פונקציית Cloud Run.
    2. בשדה שם הפונקציה, מזינים QuickStartChatApp.
    3. בקטע אזור, בוחרים אזור.
    4. בקטע 'אימות', בוחרים באפשרות דרישת אימות.
    5. לוחצים על הבא.
  4. בקטע Runtime (זמן ריצה), בוחרים את הגרסה העדכנית ביותר של Python.

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

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

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

    python/avatar-app/main.py
    from typing import Any, Mapping
    
    import flask
    import functions_framework
    
    # Command IDs (configure these in Google Chat API)
    ABOUT_COMMAND_ID = 1  # ID for the "/about" slash command
    HELP_COMMAND_ID = 2  # ID for the "Help" quick command
    
    
    @functions_framework.http
    def avatar_app(req: flask.Request) -> Mapping[str, Any]:
        """Google Cloud Function that handles HTTP requests from Google Chat.
    
        Args:
            flask.Request: the request
    
        Returns:
            Mapping[str, Any]: the response
        """
        event = req.get_json(silent=True)
    
        if event and "appCommandMetadata" in event:
            return handle_app_commands(event)
        else:
            return handle_regular_message(event)
    
    
    def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
        """Handles slash and quick commands.
    
        Args:
            Mapping[str, Any] event: The Google Chat event.
    
        Returns:
            Mapping[str, Any]: the response
        """
        app_command_id = event["appCommandMetadata"]["appCommandId"]
    
        if app_command_id == ABOUT_COMMAND_ID:
            return {
                "privateMessageViewer": event["user"],
                "text": "The Avatar app replies to Google Chat messages.",
            }
        elif app_command_id == HELP_COMMAND_ID:
            return {
                "privateMessageViewer": event["user"],
                "text": "The Avatar app replies to Google Chat messages.",
            }
        return {}
    
    
    
    
    def handle_regular_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
        """Handles regular messages (not commands).
    
        Args:
            Mapping[str, Any] event: The Google Chat event.
    
        Returns:
            Mapping[str, Any]: the response
        """
    
        if not event or "user" not in event:
            return "Invalid request."
    
        message_data = create_message(event["user"])
        return message_data
    
    
    def create_message(user: Mapping[str, Any]) -> Mapping[str, Any]:
        """Creates a card message with the user's avatar.
    
        Args:
            Mapping[str, Any] user: The user who sent the message.
    
        Returns:
            Mapping[str, Any]: a card with the user's avatar.
        """
        display_name = user.get("displayName", "")
        avatar_url = user.get("avatarUrl", "")
    
        return {
            "text": "Here's your avatar",
            "cardsV2": [
                {
                    "cardId": "avatarCard",
                    "card": {
                        "name": "Avatar Card",
                        "header": {"title": f"Hello {display_name}!"},
                        "sections": [
                            {
                                "widgets": [
                                    {"textParagraph": {"text": "Your avatar picture:"}},
                                    {"image": {"imageUrl": avatar_url}},
                                ]
                            }
                        ],
                    },
                }
            ],
        }

  8. לוחצים על פריסה.

Java

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

    כניסה לדף Cloud Functions

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

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

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

    1. בקטע סביבה, בוחרים באפשרות פונקציית Cloud Run.
    2. בשדה שם הפונקציה, מזינים QuickStartChatApp.
    3. בקטע אזור, בוחרים אזור.
    4. בקטע 'אימות', בוחרים באפשרות דרישת אימות.
    5. לוחצים על הבא.
  4. בקטע Runtime (זמן ריצה), בוחרים את הגרסה העדכנית ביותר של Java.

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

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

  7. שינוי השם של src/main/java/com/example/Example.java ל-src/main/java/AvatarApp.java.

  8. מחליפים את התוכן של AvatarApp.java בקוד הבא:

    java/avatar-app/src/main/java/AvatarApp.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.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;
    import java.util.List;
    
    public class AvatarApp implements HttpFunction {
      private static final Gson gson = new Gson();
    
      // Command IDs (configure these in Google Chat API)
      private static final int ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
      private static final int HELP_COMMAND_ID = 2; // ID for the "Help" quick command
    
      @Override
      public void service(HttpRequest request, HttpResponse response) throws Exception {
        JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
    
        if (event.has("appCommandMetadata")) {
          handleAppCommands(event, response);
        } else {
          handleRegularMessage(event, response);
        }
      }
    
      /**
       * Handles slash and quick commands.
       *
       * @param event    The Google Chat event.
       * @param response The HTTP response object.
       */
      private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
        int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();
    
        switch (appCommandId) {
          case ABOUT_COMMAND_ID:
            Message aboutMessage = new Message();
            aboutMessage.setText("The Avatar app replies to Google Chat messages.");
            aboutMessage.setPrivateMessageViewer(new User()
                .setName(event.getAsJsonObject("user").get("name").getAsString()));
            response.getWriter().write(gson.toJson(aboutMessage));
            return;
          case HELP_COMMAND_ID:
            Message helpMessage = new Message();
            helpMessage.setText("The Avatar app replies to Google Chat messages.");
            helpMessage.setPrivateMessageViewer(new User()
                .setName(event.getAsJsonObject("user").get("name").getAsString()));
            response.getWriter().write(gson.toJson(helpMessage));
            return;
        }
      }
    
      /**
       * Handles regular messages (not commands).
       *
       * @param event    The Google Chat event.
       * @param response The HTTP response object.
       */
      private void handleRegularMessage(JsonObject event, HttpResponse response) throws Exception {
    
        if (!event.has("user")) {
          response.getWriter().write("Invalid request.");
          return;
        }
    
        JsonObject user = event.getAsJsonObject("user");
        String displayName = user.has("displayName") ? user.get("displayName").getAsString() : "";
        String avatarUrl = user.has("avatarUrl") ? user.get("avatarUrl").getAsString() : "";
        Message message = createMessage(displayName, avatarUrl);
        response.getWriter().write(gson.toJson(message));
      }
    
      /**
       * Creates a card message with the user's avatar.
       *
       * @param displayName The user's display name.
       * @param avatarUrl   The URL of the user's avatar.
       * @return The card message object.
       */
      private Message createMessage(String displayName, String avatarUrl) {
        return new Message()
            .setText("Here's your avatar")
            .setCardsV2(List.of(new CardWithId()
                .setCardId("avatarCard")
                .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)))))))));
      }
    }

  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/maven-v4_0_0.xsd">
      <modelVersion>4.0.0</modelVersion>
    
      <groupId>gcfv2</groupId>
      <artifactId>avatar-app</artifactId>
      <version>0.0.1</version>
      <name>Avatar App</name>
    
      <properties>
        <maven.compiler.release>21</maven.compiler.release>
      </properties>
    
      <dependencies>
        <dependency>
          <groupId>com.google.cloud.functions</groupId>
          <artifactId>functions-framework-api</artifactId>
          <version>1.1.4</version>
        </dependency>
    
        <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
        <dependency>
          <groupId>com.google.code.gson</groupId>
          <artifactId>gson</artifactId>
          <version>2.12.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-rev20250116-2.0.0</version>
        </dependency>
    
      </dependencies>
    
    </project>

  10. לוחצים על פריסה.

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

איך מאשרים ל-Google Chat להפעיל את הפונקציה

כדי לתת ל-Google Chat הרשאה להפעיל את הפונקציה, מוסיפים את חשבון השירות של Google Chat עם התפקיד Cloud Run Invoker.

  1. במסוף Google Cloud, עוברים לדף Cloud Run:

    כניסה ל-Cloud Run

  2. ברשימת שירותי Cloud Run, מסמנים את התיבה לצד הפונקציה המקבלת. (לא לוחצים על הפונקציה עצמה).

  3. לוחצים על הרשאות. נפתחת החלונית הרשאות.

  4. לוחצים על Add principal.

  5. בשדה New principals, מזינים chat@system.gserviceaccount.com.

  6. ברשימת התפקידים Select a role בוחרים באפשרות Cloud Run > Cloud Run Invoker.

  7. לוחצים על שמירה.

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

אחרי שפורסים את Cloud Function, פועלים לפי השלבים הבאים כדי להפוך אותה לאפליקציה ל-Google Chat:

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

    כניסה לדף Cloud Functions

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

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

  3. לוחצים על הכרטיסייה Triggers (טריגרים).

  4. בקטע HTTPS, מעתיקים את כתובת ה-URL.

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

    ל-Chat API

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

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

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

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

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

  1. פותחים את Google Chat באמצעות חשבון Google Workspace שציינתם כשנוספתם כבודקים מהימנים.

    מעבר אל Google Chat

  2. לוחצים על צ'אט חדש.
  3. בשדה הוספת אדם אחד או יותר, מקלידים את השם של אפליקציית Chat.
  4. בוחרים את אפליקציית Chat מתוך התוצאות. ייפתח צ'אט ישיר.

  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 & Admin > Manage Resources.

    כניסה ל-Resource Manager

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