‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

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

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

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

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

מטרות

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

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

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

הגדרת הסביבה

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

ב-Google API Console, מפעילים את Google Chat API,‏ 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 API, עוברים לדף Cloud Run:

כניסה ל-Cloud Run

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

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

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

node/chat/avatar-app/index.js

הצגת הקוד ב-GitHub

import { http } from '@google-cloud/functions-framework';

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Handle requests from Google Workspace add on
 *
 * @param {Object} req Request sent by Google Chat
 * @param {Object} res Response to be sent back to Google Chat
 */
http('avatarApp', (req, res) => {
  const chatEvent = req.body.chat;
  let message;
  if (chatEvent.appCommandPayload) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
    message: message
  }}}});
});

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleAppCommand(event) {
  switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return {
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleMessage(event) {
  // Stores the Google Chat user as a variable.
  const chatUser = event.messagePayload.message.sender;
  const displayName = chatUser.displayName;
  const avatarUrl = chatUser.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 API, עוברים לדף Cloud Run:

כניסה ל-Cloud Run

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

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

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

python/chat/avatar-app/main.py

הצגת הקוד ב-GitHub

from typing import Any, Mapping

import flask
import functions_framework

# The ID of the slash command "/about".
# You must use the same ID in the Google Chat API configuration.
ABOUT_COMMAND_ID = 1

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Handle requests from Google Workspace add on

  Args:
    flask.Request req: the request sent by Google Chat

  Returns:
    Mapping[str, Any]: the response to be sent back to Google Chat
  """
  chat_event = req.get_json(silent=True)["chat"]
  if chat_event and "appCommandPayload" in chat_event:
    message = handle_app_command(chat_event)
  else:
    message = handle_message(chat_event)
  return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
      "message": message
  }}}}

def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to an APP_COMMAND event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
    return {
      "text": "The Avatar app replies to Google Chat messages.",
    }
  return {}

def handle_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  # Stores the Google Chat user as a variable.
  chat_user = event["messagePayload"]["message"]["sender"]
  display_name = chat_user.get("displayName", "")
  avatar_url = chat_user.get("avatarUrl", "")
  return {
    "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 API, עוברים לדף Cloud Run:

כניסה ל-Cloud Run

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

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

בקטע נקודת כניסה, מוחקים את טקסט ברירת המחדל ומזינים App.
משנים את השם של קובץ ה-Java שמוגדר כברירת מחדל ל-src/main/java/com/google/chat/avatar/App.java.
מחליפים את התוכן של App.java בקוד הבא:

java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java

הצגת הקוד ב-GitHub

package com.google.chat.avatar;

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 App implements HttpFunction {
  // The ID of the slash command "/about".
  // You must use the same ID in the Google Chat API configuration.
  private static final int ABOUT_COMMAND_ID = 1;

  private static final Gson gson = new Gson();

  /**
   * Handle requests from Google Workspace add on
   * 
   * @param request the request sent by Google Chat
   * @param response the response to be sent back to Google Chat
   */
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
    JsonObject chatEvent = event.getAsJsonObject("chat");
    Message message;
    if (chatEvent.has("appCommandPayload")) {
      message = handleAppCommand(chatEvent);
    } else {
      message = handleMessage(chatEvent);
    }
    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));
  }

  /**
   * Handles an APP_COMMAND event in Google Chat.
   *
   * @param event the event object from Google Chat
   * @return the response message object.
   */
  private Message handleAppCommand(JsonObject event) throws Exception {
    switch (event.getAsJsonObject("appCommandPayload")
      .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
      case ABOUT_COMMAND_ID:
        return new Message()
          .setText("The Avatar app replies to Google Chat messages.");
      default:
        return null;
    }
  }

  /**
   * Handles a MESSAGE event in Google Chat.
   *
   * @param event the event object from Google Chat
   * @return the response message object.
   */
  private Message handleMessage(JsonObject event) throws Exception {
    // Stores the Google Chat user as a variable.
    JsonObject chatUser = event.getAsJsonObject("messagePayload").getAsJsonObject("message").getAsJsonObject("sender");
    String displayName = chatUser.has("displayName") ? chatUser.get("displayName").getAsString() : "";
    String avatarUrl = chatUser.has("avatarUrl") ? chatUser.get("avatarUrl").getAsString() : "";
    return new Message()
      .setText("Here's your avatar")
      .setCardsV2(List.of(new CardWithId()
        .setCardId("avatarCard")
        .setCard(new GoogleAppsCardV1Card()
          .setName("Avatar Card")
          .setHeader(new GoogleAppsCardV1CardHeader()
            .setTitle(String.format("Hello %s!", displayName)))
          .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(
            new GoogleAppsCardV1Widget().setTextParagraph(new GoogleAppsCardV1TextParagraph()
              .setText("Your avatar picture:")),
            new GoogleAppsCardV1Widget()
              .setImage(new GoogleAppsCardV1Image().setImageUrl(avatarUrl)))))))));
  }
}

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

java/chat/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.1.4</version>
    </dependency>
    <dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.9.1</version>
    </dependency>
    <dependency>
      <groupId>com.google.apis</groupId>
      <artifactId>google-api-services-chat</artifactId>
      <version>v1-rev20230115-2.0.0</version>
    </dependency>
  </dependencies>

  <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. מחכים שהפונקציה תיפרס.

הגדרת אפליקציית Chat

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

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

כניסה ל-Cloud Run

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

ל-Chat API
לוחצים על Configuration (הגדרה) ומגדירים את אפליקציית Google Chat:
1. בשדה App name, מזינים Quickstart App.
2. בקטע כתובת ה-URL של האווטאר, מזינים את הערך https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png.
3. בשדה תיאור, מזינים Quickstart app.
4. בקטע פונקציונליות, בוחרים באפשרות הצטרפות למרחבים ולשיחות קבוצתיות.
5. בקטע הגדרות חיבור, בוחרים באפשרות כתובת URL של נקודת קצה HTTP.
6. בקטע Triggers (טריגרים), בוחרים באפשרות Use a common HTTP endpoint URL for all triggers (שימוש בכתובת URL משותפת של נקודת קצה מסוג HTTP לכל הטריגרים) ומדביקים את כתובת ה-URL של הטריגר של פונקציית Cloud Run בתיבה.
7. בקטע חשיפה, בוחרים באפשרות הפיכת אפליקציית Google Chat הזו לזמינה לאנשים ולקבוצות ספציפיים בדומיין ומזינים את כתובת האימייל שלכם.
8. בקטע יומנים, בוחרים באפשרות רישום שגיאות ביומן.
לוחצים על שמירה.
בקטע הגדרות חיבור, מעתיקים את האימייל של חשבון השירות. תצטרכו את כתובת האימייל הזו כשתאשרו לאפליקציית Chat להפעיל את הפונקציה.

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

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

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

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

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

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

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

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

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

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

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

מעבר אל Google Chat
לוחצים על צ'אט חדש.
בשדה Add 1 or more people (הוספת אדם אחד או יותר), מקלידים את השם של אפליקציית Chat.
בוחרים את אפליקציית Chat מתוך התוצאות. ייפתח צ'אט ישיר.

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

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

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

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

פתרון בעיות

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

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

הסרת המשאבים

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

זהירות: כשמוחקים פרויקט:

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

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

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

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

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

אפליקציות ל-Chat שהן לא תוספים: יצירת אפליקציית HTTP ל-Google Chat

כדי ליצור אפליקציית Chat שהיא לא תוסף ל-Google Workspace, צריך לפרוס את פונקציית Cloud Run, להעניק הרשאות הפעלה ולהגדיר את אפליקציית Chat שהיא לא תוסף.

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

Node.js

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

כניסה ל-Cloud Run

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

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

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

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

node/avatar-app/index.js

הצגת הקוד ב-GitHub

const functions = require('@google-cloud/functions-framework');

// Command IDs (configure these in Google Chat API)
const ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
const HELP_COMMAND_ID = 2; // ID for the "Help" quick command

/**
 * Google Cloud Function that handles HTTP requests from Google Chat.
 *
 * @param {Object} req - The HTTP request object sent from Google Chat.
 * @param {Object} res - The HTTP response object.
 */
functions.http('avatarApp', (req, res) => {
  const event = req.body;

  if (event.appCommandMetadata) {
    handleAppCommands(event, res);
  } else {
    handleRegularMessage(event, res);
  }
});

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

/**
 * Handles regular messages (not commands).
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleRegularMessage(event, res) {
  const messageData = createMessage(event.user);
  res.send(messageData);
}

/**
 * Creates a card message with the user's avatar.
 *
 * @param {Object} user - The user who sent the message.
 * @param {string} user.displayName - The user's display name.
 * @param {string} user.avatarUrl - The URL of the user's avatar.
 * @return {Object} - The card message object.
 */
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 API, עוברים לדף Cloud Run:

כניסה ל-Cloud Run

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

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

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

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

python/avatar-app/main.py

הצגת הקוד ב-GitHub

from typing import Any, Mapping

import flask
import functions_framework

# Command IDs (configure these in Google Chat API)
ABOUT_COMMAND_ID = 1  # ID for the "/about" slash command
HELP_COMMAND_ID = 2  # ID for the "Help" quick command


@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
    """Google Cloud Function that handles HTTP requests from Google Chat.

    Args:
        flask.Request: the request

    Returns:
        Mapping[str, Any]: the response
    """
    event = req.get_json(silent=True)

    if event and "appCommandMetadata" in event:
        return handle_app_commands(event)
    else:
        return handle_regular_message(event)


def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}




def handle_regular_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles regular messages (not commands).

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """

    if not event or "user" not in event:
        return "Invalid request."

    message_data = create_message(event["user"])
    return message_data


def create_message(user: Mapping[str, Any]) -> Mapping[str, Any]:
    """Creates a card message with the user's avatar.

    Args:
        Mapping[str, Any] user: The user who sent the message.

    Returns:
        Mapping[str, Any]: a card with the user's avatar.
    """
    display_name = user.get("displayName", "")
    avatar_url = user.get("avatarUrl", "")

    return {
        "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 API, עוברים לדף Cloud Run:

כניסה ל-Cloud Run

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

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

בקטע נקודת כניסה, מוחקים את טקסט ברירת המחדל ומזינים App.
שינוי השם של src/main/java/com/example/Example.java לsrc/main/java/AvatarApp.java.

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

java/avatar-app/src/main/java/AvatarApp.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.api.services.chat.v1.model.User;
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 AvatarApp implements HttpFunction {
  private static final Gson gson = new Gson();

  // Command IDs (configure these in Google Chat API)
  private static final int ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
  private static final int HELP_COMMAND_ID = 2; // ID for the "Help" quick command

  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);

    if (event.has("appCommandMetadata")) {
      handleAppCommands(event, response);
    } else {
      handleRegularMessage(event, response);
    }
  }

  /**
   * Handles slash and quick commands.
   *
   * @param event    The Google Chat event.
   * @param response The HTTP response object.
   */
  private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
    int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

    switch (appCommandId) {
      case ABOUT_COMMAND_ID:
        Message aboutMessage = new Message();
        aboutMessage.setText("The Avatar app replies to Google Chat messages.");
        aboutMessage.setPrivateMessageViewer(new User()
            .setName(event.getAsJsonObject("user").get("name").getAsString()));
        response.getWriter().write(gson.toJson(aboutMessage));
        return;
      case HELP_COMMAND_ID:
        Message helpMessage = new Message();
        helpMessage.setText("The Avatar app replies to Google Chat messages.");
        helpMessage.setPrivateMessageViewer(new User()
            .setName(event.getAsJsonObject("user").get("name").getAsString()));
        response.getWriter().write(gson.toJson(helpMessage));
        return;
    }
  }

  /**
   * Handles regular messages (not commands).
   *
   * @param event    The Google Chat event.
   * @param response The HTTP response object.
   */
  private void handleRegularMessage(JsonObject event, HttpResponse response) throws Exception {

    if (!event.has("user")) {
      response.getWriter().write("Invalid request.");
      return;
    }

    JsonObject user = event.getAsJsonObject("user");
    String displayName = user.has("displayName") ? user.get("displayName").getAsString() : "";
    String avatarUrl = user.has("avatarUrl") ? user.get("avatarUrl").getAsString() : "";
    Message message = createMessage(displayName, avatarUrl);
    response.getWriter().write(gson.toJson(message));
  }

  /**
   * Creates a card message with the user's avatar.
   *
   * @param displayName The user's display name.
   * @param avatarUrl   The URL of the user's avatar.
   * @return The card message object.
   */
  private Message createMessage(String displayName, String avatarUrl) {
    return new Message()
        .setText("Here's your avatar")
        .setCardsV2(List.of(new CardWithId()
            .setCardId("avatarCard")
            .setCard(new GoogleAppsCardV1Card()
                .setName("Avatar Card")
                .setHeader(new GoogleAppsCardV1CardHeader()
                    .setTitle(String.format("Hello %s!", displayName)))
                .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(
                    new GoogleAppsCardV1Widget()
                        .setTextParagraph(new GoogleAppsCardV1TextParagraph()
                            .setText("Your avatar picture:")),
                    new GoogleAppsCardV1Widget()
                        .setImage(new GoogleAppsCardV1Image().setImageUrl(avatarUrl)))))))));
  }
}

מחליפים את התוכן של 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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>gcfv2</groupId>
  <artifactId>avatar-app</artifactId>
  <version>0.0.1</version>
  <name>Avatar App</name>

  <properties>
    <maven.compiler.release>21</maven.compiler.release>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.1.4</version>
    </dependency>

    <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
    <dependency>
      <groupId>com.google.code.gson</groupId>
      <artifactId>gson</artifactId>
      <version>2.12.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-rev20250116-2.0.0</version>
    </dependency>

  </dependencies>

</project>

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

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

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

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

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

הגדרת אפליקציית Chat שאינה תוסף

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

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

כניסה ל-Cloud Run

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

ל-Chat API
לוחצים על הגדרה ומגדירים את אפליקציית Chat שלא מוגדרת כתוסף:
1. מבטלים את הסימון של Build this Chat app as a Google Workspace add-on (פיתוח אפליקציית Chat כתוסף ל-Google Workspace). תיפתח תיבת דו-שיח שבה תתבקשו לאשר את הפעולה. בתיבת הדו-שיח, לוחצים על השבתה.
2. בשדה App name, מזינים Quickstart App.
3. בקטע כתובת ה-URL של האווטאר, מזינים את הערך https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png.
4. בשדה תיאור, מזינים Quickstart app.
5. בקטע פונקציונליות, בוחרים באפשרות הצטרפות למרחבים ולשיחות קבוצתיות.
6. בקטע הגדרות חיבור, בוחרים באפשרות כתובת URL של נקודת קצה HTTP.
7. בקטע Triggers (טריגרים), בוחרים באפשרות Use a common HTTP endpoint URL for all triggers (שימוש בכתובת URL משותפת של נקודת קצה מסוג HTTP לכל הטריגרים) ומדביקים את כתובת ה-URL של הטריגר של פונקציית Cloud Run בתיבה.
8. בקטע חשיפה, בוחרים באפשרות הפיכת אפליקציית Chat הזו לזמינה לאנשים ולקבוצות ספציפיים בדומיין ומזינים את כתובת האימייל.
9. בקטע יומנים, בוחרים באפשרות רישום שגיאות ביומן.
לוחצים על שמירה.

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

מטרות

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

הגדרת הסביבה

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

Node.js

Python

Java

הגדרת אפליקציית Chat

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

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

פתרון בעיות

הסרת המשאבים

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

אפליקציות ל-Chat שהן לא תוספים: יצירת אפליקציית HTTP ל-Google Chat

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

Node.js

Python

Java

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

הגדרת אפליקציית Chat שאינה תוסף

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