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

יצירת אפליקציית HTTP של Google Chat באמצעות Cloud Functions

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

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

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

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

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

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

מטרות

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

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

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

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

Node.js

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

כניסה ל-Cloud Functions

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

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

Node/avatar-app/index.js

הצגת הקוד ב-GitHub

/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat room.
 *
 * @param {Object} req Request sent from Google Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Google Chat ' +
      'Room.');
  }

  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} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

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

Python

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

כניסה ל-Cloud Functions

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

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

python/avatar-app/main.py

הצגת הקוד ב-GitHub

from typing import Any, Mapping

import flask
import functions_framework


# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request) -> Mapping[str, Any]:
  if req.method == "GET":
    return "Hello! This function must be called from Google Chat."

  request_json = req.get_json(silent=True)

  display_name = request_json["message"]["sender"]["displayName"]
  avatar = request_json["message"]["sender"]["avatarUrl"]

  response = create_message(name=display_name, image_url=avatar)

  return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
  avatar_image_widget = {"image": {"imageUrl": image_url}}
  avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
  avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

  header = {"title": f"Hello {name}!"}

  cards = {
      "text": "Here's your avatar",
      "cardsV2": [
          {
              "cardId": "avatarCard",
              "card": {
                  "name": "Avatar Card",
                  "header": header,
                  "sections": [avatar_section],
              },
          }
      ]
  }

  return cards

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

Java

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

כניסה ל-Cloud Functions

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

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

java/avatar-app/src/main/java/HelloChat.java

הצגת הקוד ב-GitHub

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;
import java.util.List;

public class HelloChat 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("message")) {
      response.getWriter().write("Hello! This function must be called from Google Chat.");
      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>cloudfunctions</groupId>
  <artifactId>http-function</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.target>11</maven.compiler.target>
    <maven.compiler.source>11</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 Functions, פועלים לפי השלבים הבאים כדי להפוך אותה לאפליקציית Google Chat:

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

כניסה ל-Cloud Functions

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

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

אפליקציית 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 ואדמין > ניהול משאבים.
כניסה למנהל המשאבים
ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete .
כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

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

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