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

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

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

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

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

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

מטרות

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

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

• חשבון Google Workspace בתוכנית Business או Enterprise עם גישה ל-Google Chat.
• פרויקט ב-Google Cloud שמופעל בו חיוב. כדי לבדוק אם החיוב מופעל בפרויקט קיים, קראו את המאמר אימות סטטוס החיוב של הפרויקטים. במאמר יצירת פרויקט ב-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 ופריסה שלה, שיוצרות כרטיס ב-Chat עם השם המוצג ותמונת הדמות של השולח. כשאפליקציית Chat מקבלת הודעה, היא מפעילה את הפונקציה ומגיבה בכרטיס.

כדי ליצור ולפרוס את הפונקציה לאפליקציית Chat:

Node.js

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

   כניסה אל Cloud Functions

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

2. לוחצים על Create Function.

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

   1. בקטע Environment, בוחרים באפשרות Cloud Run Function.
   2. בשדה Function name, מזינים QuickStartChatApp.
   3. בקטע אזור, בוחרים אזור.
   4. בקטע 'אימות', בוחרים באפשרות דרישת אימות.
   5. לוחצים על הבא.

4. בקטע Runtime, בוחרים את הגרסה האחרונה של Node.js.

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

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

7. מחליפים את התוכן של 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 }
           }]}]
         }
       }]
     };
   }

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

Python

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

   כניסה אל Cloud Functions

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

2. לוחצים על Create Function.

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

   1. בקטע Environment, בוחרים באפשרות Cloud Run Function.
   2. בשדה Function name, מזינים QuickStartChatApp.
   3. בקטע אזור, בוחרים אזור.
   4. בקטע 'אימות', בוחרים באפשרות דרישת אימות.
   5. לוחצים על הבא.

4. בקטע Runtime, בוחרים את הגרסה האחרונה של Python.

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

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

7. מחליפים את התוכן של 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 }
               }]
             }]
         }
       }]
     }

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

Java

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

   כניסה אל Cloud Functions

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

2. לוחצים על Create Function.

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

   1. בקטע Environment, בוחרים באפשרות Cloud Run Function.
   2. בשדה Function name, מזינים QuickStartChatApp.
   3. בקטע אזור, בוחרים אזור.
   4. בקטע 'אימות', בוחרים באפשרות דרישת אימות.
   5. לוחצים על הבא.

4. בקטע Runtime, בוחרים את הגרסה האחרונה של Java.

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

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

7. משנים את השם של src/main/java/com/example/Example.java ל-src/main/java/App.java.

8. מחליפים את התוכן של 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)))))))));
     }
   }

9. מחליפים את התוכן של 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>

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

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

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

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

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

   כניסה אל Cloud Run

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

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

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

5. בשדה New principals, מזינים [e-mail].

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. בקטע Avatar URL, מזינים את הערך https://developers.google.com/chat/images/quickstart-app-avatar.png.
   3. בשדה Description, מזינים Quickstart app.
   4. בקטע Functionality, בוחרים באפשרות קבלת הודעות אישיות והצטרפות למרחבים משותפים ולשיחות קבוצתיות.
   5. בקטע Connection settings (הגדרות חיבור), בוחרים באפשרות HTTP endpoint URL (כתובת ה-URL של נקודת הקצה ב-HTTP) ומדביקים בתיבה את כתובת ה-URL של הטריגר של הפונקציה של Cloud Functions.
   6. בקטע Authentication Audience, בוחרים באפשרות HTTP endpoint URL.
   7. בקטע Visibility, בוחרים באפשרות הפיכת אפליקציית Google Chat הזו לזמינה לאנשים ולקבוצות ספציפיים בדומיין ומזינים את כתובת האימייל.
   8. בקטע Logs (יומנים), בוחרים באפשרות Log errors to Logging (רישום שגיאות ביומן).

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

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

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

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

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

   כניסה ל-Google Chat

2. לוחצים על צ'אט חדש.
3. בשדה Add 1 or more people, מקלידים את שם אפליקציית Chat.

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

   הערה: אם אפליקציית Chat לא מופיעה ברשימת התוצאות, צריך לוודא שכללתם את חשבון Google Workspace בהגדרות החשיפה בדף הגדרת Chat API במסוף Google Cloud.
5. בצ'אט האישי החדש עם האפליקציה, מקלידים Hello ומקישים על enter.

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

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

פתרון בעיות

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

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

הסרת המשאבים

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

זהירות: כשמוחקים פרויקט:

• התוכן של הפרויקט נמחק כולו. אם השתמשתם בפרויקט קיים כדי לתרגל את המדריך הזה, כשתמחקו אותו תימחק גם כל העבודה שביצעתם באותו פרויקט.
• מאבדים את מזהה הפרויקט בהתאמה אישית. כשיצרתם את הפרויקט, יכולתם לבחור לו מזהה פרויקט בהתאמה אישית כדי להשתמש בו בעתיד. כדי לשמור על כתובות ה-URL שמשתמשות במזהה הפרויקט, כמו כתובת URL ב-appspot.com, צריך למחוק את המשאבים שנבחרו בפרויקט אבל לא את הפרויקט כולו.

אם אתם מתכננים להיעזר במספר מדריכי לימוד או מדריכים למתחילים, מומלץ להשתמש שוב באותו פרויקט כדי לא לחרוג ממכסות הפרויקטים.

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

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

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

נושאים קשורים

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

  • יצירת הודעות אינטראקטיביות בכרטיסים
  • תגובה לפקודות דרך שורת הפקודה
  • פתיחה של תיבות דו-שיח ותשובה להן

• בחירת ארכיטקטורה של אפליקציית Chat

• אימות בקשות מ-Google Chat