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

בדף הזה מוסבר איך לבנות תוסף ל-Google Workspace שפועל ב-Google Chat באמצעות שירות HTTP.

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

באמצעות ארכיטקטורת HTTP, אתם מגדירים את 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.
  • הגדרת תוסף ל-Google Workspace באפליקציית Chat.
  • בודקים את האפליקציה.

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

הגדרת הסביבה

לפני שמשתמשים בממשקי Google API, צריך להפעיל אותם בפרויקט ב-Google Cloud. אפשר להפעיל ממשק API אחד או יותר בפרויקט יחיד ב-Google Cloud.
  • במסוף Google Cloud, מפעילים את 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. בקטע Environment (סביבה), בוחרים באפשרות Cloud Run Function (פונקציית Cloud Run).
    2. בשדה שם הפונקציה, מזינים AddOnChatApp.
    3. בקטע אזור, בוחרים אזור.
    4. בקטע 'אימות', בוחרים באפשרות דרישת אימות.
    5. לוחצים על הבא.
  4. בקטע סביבת זמן ריצה, בוחרים את הגרסה העדכנית ביותר של Node.js.

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

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

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

Python

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

    כניסה לדף Cloud Functions

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

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

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

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

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

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

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

Java

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

    כניסה לדף Cloud Functions

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

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

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

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

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

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

  7. משנים את השם של קובץ ה-Java שמוגדר כברירת מחדל ל-src/main/java/AvatarApp.java.

  8. מחליפים את התוכן של 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;
        }
    }
    
  9. מחליפים את התוכן של 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>
    
  10. לוחצים על פריסה.

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

הגדרת התוסף

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

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

    כניסה לדף Cloud Functions

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

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

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

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

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

    ל-Chat API

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

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

לאחר מכן, מאשרים לאפליקציית Chat להפעיל את פונקציית Cloud.

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

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

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

    כניסה ל-Cloud Run

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

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

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

  5. בשדה New principals, מזינים את כתובת האימייל של חשבון השירות של תוסף Google Workspace שמשויך לפרויקט. כתובת האימייל של חשבון השירות מופיעה בקטע Connection settings (הגדרות חיבור) > HTTP endpoint URL (כתובת URL של נקודת קצה של HTTP) > Service Account Email (כתובת האימייל של חשבון השירות) בדף ההגדרות של Chat API:

    כניסה להגדרות של Chat API

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

  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.