בדף הזה מוסבר איך ליצור תוסף ל-Google Workspace שפועל ב-Google Chat באמצעות שירות HTTP. בתוספים ב-Google Chat, המשתמשים רואים אותם כאפליקציות של Google Chat. מידע נוסף זמין בקטע סקירה כללית על הרחבת Google Chat.
במדריך למתחילים הזה נסביר איך יוצרים שירות HTTP באמצעות שירותי Google Cloud. כדי ליצור את אפליקציית Chat, כותבים ומפרסים פונקציית Cloud שבאמצעותה אפליקציית Chat מגיבה להודעה של משתמש.
בארכיטקטורת HTTP, מגדירים את Chat כך שישתלב עם Google Cloud או עם שרת מקומי באמצעות HTTP, כפי שמתואר בתרשים הבא:
בתרשים הקודם, כשמשתמש יוצר אינטראקציה עם אפליקציית HTTP Chat, מתרחש תהליך העברת המידע הבא:
- משתמש שולח הודעה ב-Chat לאפליקציית Chat, בצ'אט אישי או במרחב משותף ב-Chat.
- בקשת HTTP נשלחת לשרת אינטרנט, שהוא מערכת בענן או מערכת מקומית שמכילה את הלוגיקה של אפליקציית Chat.
- אפשר גם לשלב את הלוגיקה של אפליקציית Chat עם שירותי Google Workspace (כמו יומן Google ו-Sheets), שירותי Google אחרים (כמו מפות Google, YouTube ו-Vertex AI) או שירותי אינטרנט אחרים (כמו מערכת לניהול פרויקטים או כלי ליצירת כרטיסים).
- שרת האינטרנט שולח תגובת HTTP בחזרה לשירות של אפליקציית Chat ב-Chat.
- התשובה מועברת למשתמש.
- אפשר גם להשתמש ב-Chat API כדי לפרסם הודעות באופן אסינכררוני או לבצע פעולות אחרות.
הארכיטקטורה הזו מספקת גמישות לשימוש בספריות וברכיבים שכבר קיימים במערכת, כי אפשר לתכנן את אפליקציות הצ'אט האלה באמצעות שפות תכנות שונות.
מטרות
- מגדירים את הסביבה.
- יוצרים פונקציה ב-Cloud Functions ופורסים אותה.
- מגדירים תוסף של Google Workspace לאפליקציית 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.
יצירה ופריסה של פונקציה ב-Cloud Functions
יצירת פונקציית Cloud ופריסה שלה, שיוצרת כרטיס ב-Chat עם השם המוצג ותמונת הדמות של השולח. כשמתקבלת הודעה באפליקציית Chat, הפונקציה מופעלת והיא משיבה באמצעות הכרטיס.
כדי ליצור ולפרוס את הפונקציה לאפליקציית Chat:
Node.js
נכנסים לדף Cloud Functions במסוף Google Cloud:
מוודאים שבחרתם את הפרויקט של אפליקציית Chat.
לוחצים על
Create Function.בדף Create function, מגדירים את הפונקציה:
- בקטע Environment, בוחרים באפשרות Cloud Run Function.
- בשדה Function name, מזינים
AddOnChatApp
. - בקטע אזור, בוחרים אזור.
- בקטע 'אימות', בוחרים באפשרות דרישת אימות.
- לוחצים על הבא.
בקטע Runtime, בוחרים את הגרסה האחרונה של Node.js.
בקטע קוד מקור, בוחרים באפשרות עורך בשורה.
בקטע Entry point (נקודת כניסה), מוחקים את טקסט ברירת המחדל ומזינים
avatarApp
.מחליפים את התוכן של
index.js
בקוד הבא:/** * 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.chat) { 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 chatMessage = req.body.chat.messagePayload.message; // Replies with the sender's avatar in a card. const displayName = chatMessage.sender.displayName; const avatarUrl = chatMessage.sender.avatarUrl; res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: { 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 } }] }] } }] }}}}}); };
לוחצים על פריסת.
Python
נכנסים לדף Cloud Functions במסוף Google Cloud:
מוודאים שבחרתם את הפרויקט של אפליקציית Chat.
לוחצים על
Create Function.בדף Create function, מגדירים את הפונקציה:
- בקטע Environment, בוחרים באפשרות Cloud Run Function.
- בשדה Function name, מזינים
AddOnChatApp
. - בקטע אזור, בוחרים אזור.
- בקטע 'אימות', בוחרים באפשרות דרישת אימות.
- לוחצים על הבא.
בקטע Runtime, בוחרים את הגרסה האחרונה של Python.
בקטע קוד מקור, בוחרים באפשרות עורך בשורה.
בקטע Entry point (נקודת כניסה), מוחקים את טקסט ברירת המחדל ומזינים
avatar_app
.מחליפים את התוכן של
main.py
בקוד הבא:from typing import Any, Mapping import flask import functions_framework @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) # Stores the Google Chat event as a variable. chat_message = request_json["chat"]["messagePayload"]["message"] # Replies with the sender's avatar in a card. display_name = chat_message["sender"]["displayName"] avatar_url = chat_message["sender"]["avatarUrl"] return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": { "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 } }] }] } }] }}}}}
לוחצים על פריסת.
Java
נכנסים לדף Cloud Functions במסוף Google Cloud:
מוודאים שבחרתם את הפרויקט של אפליקציית Chat.
לוחצים על
Create Function.בדף Create function, מגדירים את הפונקציה:
- בקטע Environment, בוחרים באפשרות Cloud Run Function.
- בשדה Function name, מזינים
AddOnChatApp
. - בקטע אזור, בוחרים אזור.
- בקטע 'אימות', בוחרים באפשרות דרישת אימות.
- לוחצים על הבא.
בקטע Runtime, בוחרים את הגרסה האחרונה של Java.
בקטע קוד מקור, בוחרים באפשרות עורך בשורה.
בקטע Entry point (נקודת כניסה), מוחקים את טקסט ברירת המחדל ומזינים
AvatarApp
.משנים את שם קובץ ברירת המחדל של Java ל-
src/main/java/AvatarApp.java
.מחליפים את התוכן של
AvatarApp.java
בקוד הבא: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.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 AvatarApp 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("chat")) { response.getWriter().write("Hello! This function is meant to be used " + "in a Google Chat Space.."); return; } // Stores the Google Chat event as a variable. JsonObject chatMessage = body.getAsJsonObject("chat") .getAsJsonObject("messagePayload").getAsJsonObject("message"); // Replies with the sender's avatar in a card. String displayName = chatMessage.getAsJsonObject("sender").get("displayName").getAsString(); String avatarUrl = chatMessage.getAsJsonObject("sender").get("avatarUrl").getAsString(); Message message = createMessage(displayName, avatarUrl); JsonObject createMessageAction = new JsonObject(); createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class)); JsonObject chatDataAction = new JsonObject(); chatDataAction.add("createMessageAction", createMessageAction); JsonObject hostAppDataAction = new JsonObject(); hostAppDataAction.add("chatDataAction", chatDataAction); JsonObject dataActions = new JsonObject(); dataActions.add("hostAppDataAction", hostAppDataAction); response.getWriter().write(gson.toJson(dataActions)); } 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("avatarCard"); cardWithId.setCard(card); Message message = new Message(); message.setText("Here's your avatar"); message.setCardsV2(List.of(cardWithId)); return message; } }
מחליפים את התוכן של
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>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.4</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 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>
לוחצים על פריסת.
דף הפרטים של Cloud Functions נפתח, והפונקציה מופיעה עם שני מדדי התקדמות: אחד ל-build ואחד לשירות. כששני מדדי ההתקדמות נעלמים ומוחלפים בסימן וי, הפונקציה פרוסה ומוכנה לשימוש.
מתן הרשאה ל-Google Chat להפעיל את הפונקציה
כדי לתת הרשאה לתוסף Google Workspace להפעיל את הפונקציה, מוסיפים את חשבון השירות של התוסף ל-Google Workspace עם התפקיד Cloud Run Invoker.
נכנסים לדף Cloud Run במסוף Google Cloud:
ברשימה של שירותי Cloud Run, מסמנים את התיבה שלצד הפונקציה המקבלת. (לא לוחצים על הפונקציה עצמה).
לוחצים על הרשאות. החלונית Permissions (הרשאות) נפתחת.
לוחצים על Add principal.
בשדה New principals, מזינים את כתובת האימייל של חשבון השירות של התוסף ל-Google Workspace שמשויך לפרויקט.
בקטע Select a role, בוחרים באפשרות Cloud Run > Cloud Run Invoker.
לוחצים על שמירה.
הגדרת התוסף
אחרי הפריסה של Cloud Function, מבצעים את השלבים הבאים כדי ליצור תוסף ולפרוס את אפליקציית Google Chat:
במסוף Google Cloud, לוחצים על סמל התפריט > Cloud Functions.
מוודאים שבחרתם את הפרויקט שבו הפעלתם את Cloud Functions.
ברשימת הפונקציות, לוחצים על AddOnChatApp.
לוחצים על הכרטיסייה טריגרים.
בקטע HTTPS, מעתיקים את כתובת ה-URL.
מחפשים את 'Google Chat API' ולוחצים על Google Chat API ואז על ניהול.
לוחצים על הגדרה ומגדירים את אפליקציית Google Chat:
- בשדה App name, מזינים
Add-on Chat app
. - בקטע Avatar URL, מזינים את הערך
https://developers.google.com/chat/images/quickstart-app-avatar.png
. - בשדה Description, מזינים
Add-on Chat app
. - בקטע פונקציונליות, בוחרים באפשרויות קבלת הודעות בצ'אט אישי והצטרפות למרחבים משותפים ולשיחות קבוצתיות.
- בקטע Connection settings, בוחרים באפשרות HTTP endpoint URL ומדביקים את כתובת ה-URL של הטריגר של Cloud Function בתיבה.
- בקטע Authentication Audience, בוחרים באפשרות HTTP endpoint URL.
- בקטע Visibility (חשיפה), בוחרים באפשרות Make this Google Chat app available to specific people and groups (האפליקציה של Google Chat תהיה זמינה לאנשים ולקבוצות ספציפיים) בדומיין ומזינים את כתובת האימייל.
- בקטע יומנים, בוחרים באפשרות רישום שגיאות ביומן.
- בשדה App name, מזינים
לוחצים על שמירה.
אפליקציית Chat מוכנה לקבל הודעות ולענות להן ב-Chat.
בדיקת אפליקציית Chat
כדי לבדוק את אפליקציית Chat, פותחים מרחב משותף בצ'אט אישי באפליקציה ושולחים הודעה:
פותחים את Google Chat באמצעות חשבון Google Workspace שסיפקתם כשהוספת את עצמכם כבודקים מהימנים.
- לוחצים על צ'אט חדש.
- בשדה Add 1 or more people, מקלידים את שם אפליקציית Chat.
בוחרים את אפליקציית Chat בתוצאות. ייפתח צ'אט אישי.
- בצ'אט האישי החדש עם האפליקציה, מקלידים
Hello
ומקישים עלenter
.
ההודעה באפליקציית Chat מכילה כרטיס שבו מוצגים השם של השולח ותמונת הדמות שלו, כפי שמוצג בתמונה הבאה:
במאמר בדיקת תכונות אינטראקטיביות באפליקציות של Google Chat מוסבר איך מוסיפים בודקים מהימנים ומידע נוסף על בדיקת תכונות אינטראקטיביות.
פתרון בעיות
כשכרטיס או אפליקציית Google Chat מחזירים שגיאה, בממשק Chat מופיעה ההודעה "משהו השתבש". או "לא ניתן לעבד את הבקשה שלך". לפעמים בממשק המשתמש של Chat לא מוצגת הודעת שגיאה, אבל באפליקציה או בכרטיס של Chat מתקבלת תוצאה לא צפויה. לדוגמה, יכול להיות שלא תוצג הודעה בכרטיס.
יכול להיות שהודעת שגיאה לא תוצג בממשק המשתמש של Chat, אבל כשיומני השגיאות של אפליקציות Chat מופעלים, יהיו זמינות הודעות שגיאה תיאוריות ונתוני יומנים שיעזרו לכם לתקן שגיאות. במאמר פתרון בעיות ושגיאות ב-Google Chat מוסבר איך מציגים, מאתרים באגים ומתקנים שגיאות.
הסרת המשאבים
כדי להימנע מחיובים בחשבון Google Cloud בגלל השימוש במשאבים שנעשה במסגרת המדריך הזה, מומלץ למחוק את הפרויקט ב-Cloud.
- במסוף Google Cloud, עוברים לדף Manage resources. לוחצים על תפריט > IAM & Admin > Manage Resources.
- ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete .
- כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.