דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

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

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

מטרות

מגדירים את הסביבה.
יוצרים ופורסים פונקציית Cloud Run.
הגדרת תוסף ל-Google Workspace באפליקציית Chat.
בודקים את האפליקציה.

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

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

הגדרת הסביבה

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

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

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

Node.js

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

כניסה ל-Cloud Run

מוודאים שהפרויקט של אפליקציית Chat נבחר.
לוחצים על כתיבת פונקציה.
בדף Create service (יצירת שירות), מגדירים את הפונקציה:
1. בשדה שם השירות מזינים addonchatapp.
2. בוחרים אזור מהרשימה אזור.
3. ברשימה Runtime (סביבת זמן ריצה), בוחרים את הגרסה העדכנית ביותר של Node.js.
4. בקטע Authentication, בוחרים באפשרות Require authentication.
5. לוחצים על Create (יצירה) ומחכים ש-Cloud Run ייצור את השירות. המסוף מפנה אתכם לכרטיסייה מקור.

בכרטיסייה מקור:

בקטע נקודת כניסה, מוחקים את טקסט ברירת המחדל ומזינים avatarApp.
מחליפים את התוכן של index.js בקוד הבא:

/**
 * Google Cloud Run 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
 */
import { http } from '@google-cloud/functions-framework';

http('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 }
                    }]
                }]
            }
        }]
    }}}}});
});

מחליפים את התוכן של package.json בקוד הבא:

{
  "name": "avatar-app",
  "version": "1.0.0",
  "description": "Google Chat Avatar App",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}

לוחצים על שמירה ופריסה מחדש.

Python

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

כניסה ל-Cloud Run

מוודאים שהפרויקט של אפליקציית Chat נבחר.
לוחצים על כתיבת פונקציה.
בדף Create service (יצירת שירות), מגדירים את הפונקציה:
1. בשדה שם השירות מזינים addonchatapp.
2. בוחרים אזור מהרשימה אזור.
3. ברשימה Runtime (סביבת זמן ריצה), בוחרים את הגרסה העדכנית ביותר של Python.
4. בקטע Authentication, בוחרים באפשרות Require authentication.
5. לוחצים על Create (יצירה) ומחכים ש-Cloud Run ייצור את השירות. המסוף מפנה אתכם לכרטיסייה מקור.

בכרטיסייה מקור:

בקטע נקודת כניסה, מוחקים את טקסט ברירת המחדל ומזינים 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 Run 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

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

כניסה ל-Cloud Run

מוודאים שהפרויקט של אפליקציית Chat נבחר.
לוחצים על כתיבת פונקציה.
בדף Create service (יצירת שירות), מגדירים את הפונקציה:
1. בשדה שם השירות מזינים addonchatapp.
2. בוחרים אזור מהרשימה אזור.
3. ברשימה Runtime בוחרים בגרסה העדכנית ביותר של Java.
4. בקטע Authentication, בוחרים באפשרות Require authentication.
5. לוחצים על Create (יצירה) ומחכים ש-Cloud Run ייצור את השירות. המסוף מפנה אתכם לכרטיסייה מקור.

בכרטיסייה מקור:

בקטע נקודת כניסה, מוחקים את טקסט ברירת המחדל ומזינים AvatarApp.
משנים את השם של קובץ ה-Java שמוגדר כברירת מחדל ל-src/main/java/gcfv2/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 Run. ממתינים לפריסת הפונקציה.

הגדרת התוסף

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

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

כניסה ל-Cloud Run

מוודאים שהפרויקט שבו הפעלתם את Cloud Run נבחר.
ברשימת הפונקציות, לוחצים על addonchatapp.
בדף פרטי השירות, מעתיקים את כתובת ה-URL של הפונקציה. כתובת ה-URL מסתיימת ב-run.app.
בשדה החיפוש של Google Cloud, מחפשים את Google Chat API, לוחצים על Google Chat API ואז על ניהול.

ל-Chat API
לוחצים על הגדרה ומגדירים את אפליקציית 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).
6. מעתיקים את כתובת האימייל של חשבון השירות. תצטרכו את כתובת האימייל הזו כדי לתת לתוסף הרשאה להפעיל את הפונקציה.
7. בקטע Triggers (טריגרים), בוחרים באפשרות Use a common HTTP endpoint URL for all triggers (שימוש בכתובת URL משותפת של נקודת קצה מסוג HTTP לכל הטריגרים) ומדביקים את כתובת ה-URL של הטריגר של פונקציית Cloud Run בתיבה.
8. בקטע חשיפה, בוחרים באפשרות הפיכת האפליקציה הזו של Google Chat לזמינה לאנשים ולקבוצות ספציפיים בדומיין ומזינים את כתובת האימייל.
9. בקטע יומנים, בוחרים באפשרות רישום שגיאות ביומן.
לוחצים על שמירה.

בשלב הבא, מאשרים לאפליקציית Chat להפעיל את פונקציית Cloud Run.

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

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

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

כניסה ל-Cloud Run
ברשימת שירותי Cloud Run, מסמנים את התיבה לצד הפונקציה המקבלת. (לא לוחצים על הפונקציה עצמה).
לוחצים על הרשאות. נפתחת החלונית הרשאות.
לוחצים על Add principal.
בשדה New principals, מזינים את כתובת האימייל של חשבון השירות של תוסף Google Workspace שמשויך לאפליקציית Chat.

כתובת האימייל של חשבון השירות מופיעה בדף ההגדרות של Chat API, בקטע Connection settings (הגדרות חיבור) > HTTP endpoint URL (כתובת URL של נקודת קצה של HTTP) > Service Account Email (אימייל של חשבון שירות):

כניסה להגדרות של Chat API
ברשימת התפקידים Select a role בוחרים באפשרות Cloud Run > Cloud Run Service Invoker.
לוחצים על שמירה.

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

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

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

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

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

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

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

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

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

פתרון בעיות

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

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

הסרת המשאבים

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

חשוב לדעת: כשמוחקים פרויקט:

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

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

במסוף Google Cloud, עוברים לדף Manage resources. לוחצים על תפריט > IAM & Admin > Manage Resources.
כניסה ל-Resource Manager
ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete .
כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

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

מטרות

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

הגדרת הסביבה

יצירה ופריסה של פונקציית Cloud Run

Node.js

Python

Java

הגדרת התוסף

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

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

פתרון בעיות

הסרת המשאבים

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