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

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

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

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

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

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

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

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

מטרות

מגדירים את הסביבה.
יצירה ופריסה של פונקציה ב-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

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

כניסה אל Cloud Functions

מוודאים שבחרתם את הפרויקט של אפליקציית Chat.
לוחצים על Create Function.
בדף Create function, מגדירים את הפונקציה:
1. בקטע Environment, בוחרים באפשרות 2nd gen.
2. בשדה Function name, מזינים QuickStartChatApp.
3. בקטע אזור, בוחרים אזור.
4. בקטע 'אימות', בוחרים באפשרות דרישת אימות.
5. לוחצים על הבא.
בקטע Runtime, בוחרים את הגרסה האחרונה של Node.js.
בקטע קוד מקור, בוחרים באפשרות עורך מוטבע.
בשדה Entry point (נקודת כניסה), מוחקים את טקסט ברירת המחדל ומזינים avatarApp.

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

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

Python

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

כניסה ל-Cloud Functions

צריך לוודא שהפרויקט באפליקציית Chat נבחר.
לוחצים על Create Function.
בדף Create function, מגדירים את הפונקציה:
1. בקטע Environment, בוחרים באפשרות 2nd gen.
2. בשדה Function name, מזינים QuickStartChatApp.
3. בקטע אזור, בוחרים אזור.
4. בקטע 'אימות', בוחרים באפשרות דרישת אימות.
5. לוחצים על הבא.
בקטע סביבת זמן הריצה, בוחרים את הגרסה העדכנית ביותר של Python.
בקטע קוד מקור, בוחרים באפשרות עורך מוטבע.
בקטע נקודת כניסה, מוחקים את טקסט ברירת המחדל ומזינים avatar_app.

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

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

Java

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

כניסה ל-Cloud Functions

צריך לוודא שהפרויקט באפליקציית Chat נבחר.
לוחצים על Create Function.
בדף Create function, מגדירים את הפונקציה:
1. בקטע Environment, בוחרים באפשרות 2nd gen.
2. בשדה Function name, מזינים QuickStartChatApp.
3. בקטע אזור, בוחרים אזור.
4. בקטע 'אימות', בוחרים באפשרות דרישת אימות.
5. לוחצים על הבא.
בקטע סביבת זמן הריצה, בוחרים בגרסה העדכנית ביותר של Java.
בקטע קוד מקור, בוחרים באפשרות עורך בתוך שורת הטקסט.
בשדה Entry point (נקודת כניסה), מוחקים את טקסט ברירת המחדל ומזינים App.
שינוי השם של src/main/java/com/example/Example.java לשם src/main/java/App.java.

מחליפים את התוכן של 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.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:
        JsonObject aboutMessage = new JsonObject();
        aboutMessage.addProperty("text", "The Avatar app replies to Google Chat messages.");
        aboutMessage.add("privateMessageViewer", body.getAsJsonObject("user"));
          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) {
    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("previewLink");
    cardWithId.setCard(card);

    Message message = new Message();
    message.setText("Here's your avatar");
    message.setCardsV2(List.of(cardWithId));

    return message;
  }
}

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

לוחצים על Deploy (פריסה).

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

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

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

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

כניסה אל Cloud Run
ברשימת השירותים של Cloud Run, מסמנים את התיבה שליד מותאמת אישית. (אין ללחוץ על הפונקציה עצמה).
לוחצים על הרשאות. החלונית Permissions תיפתח.
לוחצים על Add principal.
בשדה New principals, מזינים chat@system.gserviceaccount.com.
בקטע Select a role, בוחרים באפשרות Cloud Run‏ > Cloud Run Invoker.
לוחצים על שמירה.

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

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

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

כניסה אל Cloud Functions

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

כניסה ל-Chat API
לוחצים על הגדרה ומגדירים את אפליקציית 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. בקטע פונקציונליות, בוחרים באפשרויות קבלת הודעות בצ'אט אישי והצטרפות למרחבים משותפים ולשיחות קבוצתיות.
5. בקטע Connection settings (הגדרות חיבור), בוחרים באפשרות HTTP endpoint (כתובת ה-URL של נקודת הקצה ב-HTTP) ומדביקים את כתובת ה-URL של את הטריגר של הפונקציה של Cloud Functions.
6. בקטע Authentication Audience, בוחרים באפשרות HTTP endpoint URL.
7. בקטע חשיפה, בוחרים אפליקציית Google Chat הזו תהיה זמינה לאנשים ספציפיים קבוצות בדומיין שלך ולהזין את כתובת האימייל שלך.
8. בקטע Logs (יומנים), בוחרים באפשרות Log errors to Logging (רישום שגיאות ביומן).
לוחצים על שמירה.

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

איך בודקים את אפליקציית Chat

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

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

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

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

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

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

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

פתרון בעיות

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

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

הסרת המשאבים

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

זהירות: למחיקת פרויקט יש את ההשפעות הבאות:

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

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

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

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

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