יצירת אפליקציות ל-Google Chat עם Gemini

1. לפני שמתחילים

מהן אפליקציות ל-Google Chat עם Gemini?

אפליקציות של Google Chat עם Gemini עושות את הפעולות הבאות:

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

למה כדאי לשלב אפליקציות של Google Chat עם Gemini?

תרחישי השימוש האופייניים במודלים של AI גנרטיבי כמו Gemini נכללים בקטגוריות הבאות:

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

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

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

ידע בסיסי ב- Apps Script, ב- Google Cloud וב- Node.js.
ידע בסיסי במושגים של Google Chat, כולל event handlers,‏ slash commands,‏ dialogs,‏ cards,‏ messages,‏ app authentication ו-APIs.

מה תפתחו

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

אפליקציה לניהול בעיות (יצירת תוכן ושיפורו)

האפליקציה הזו מבצעת את הפעולות הבאות:

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

אתם יכולים להשתמש ב-Gemini כדי:

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

הטכנולוגיות העיקריות שבהן נעשה שימוש הן Vertex AI,‏ Gemini,‏ Apps Script וממשקי API של Google Workspace (Admin,‏ Chat,‏ Docs,‏ Events).

אפליקציית Knowledge (חיפוש נתונים)

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

הטכנולוגיות העיקריות שבהן נעשה שימוש הן סוכן מאגר נתונים של Dialogflow CX,‏ webhook של Dialogflow CX,‏ Google Cloud Functions ו-Gemini.

אפליקציית משוב (שיחה)

האפליקציה הזו מסתמכת על Gemini כדי לאסוף ולשמור ביקורות עם שיחות בשפה טבעית.

הטכנולוגיות העיקריות שבהן נעשה שימוש הן סוכן Dialogflow CX, כלי Dialogflow CX,‏ OpenAPI,‏ Google Cloud Functions ו-Gemini.

מה תלמדו

איך משלבים אפליקציות של Google Chat עם Gemini דרך Vertex AI.
איך משלבים אפליקציות של Google Chat עם סוכנים של Dialogflow CX.
איך משתמשים בתכונות החדשות של Google Chat: דף הבית של האפליקציה, אירועים ב-Google Chat ווידג'טים של אביזרים.

מה צריך

השלמת המדריך למתחילים של יצירת אפליקציית צ'אט ל-Google Chat באמצעות Apps Script. ה-Codelab הזה מבוסס על פרויקט Google Cloud ועל פרויקט Apps Script שנוצרו.

2. להגדרה

הפעלת משאבים

בקטע הזה נסביר איך לגשת למשאבים הבאים ולהגדיר אותם מדפדפן האינטרנט המועדף.

פרויקט Apps Script

ב-Apps Script console, פועלים לפי השלבים הבאים:

לוחצים על הגדרות ומפעילים את Google Apps Script API.

בוחרים את הפרויקט הרצוי.
לוחצים על Project settings (הגדרות הפרויקט).
מסמנים את תיבת הסימון הצגת קובץ המניפסט appsscript.jsonבעורך.
משנים את שם הפרויקט ל-Chat Apps Gemini.

פרויקט בענן של Google Cloud

במסוף Google Cloud, פועלים לפי השלבים הבאים:

בוחרים את הפרויקט הרצוי.
לוחצים על תפריט ☰ > ממשקי API ושירותים > מסך הסכמה ל-OAuth > עריכת האפליקציה, ואז מגדירים את שם האפליקציה ל-Chat Apps Gemini.

עוברים להגדרה של Google Chat API, ואז מגדירים את שם האפליקציה והתיאור ל-Chat Apps Gemini.

Google Chat

ב-Google Chat, פועלים לפי השלבים הבאים:

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

הורדת קוד המקור והמשאבים באופן מקומי

מורידים את מאגר GitHub הזה.

בסביבת הפיתוח המועדפת, פותחים את הספרייה apps-script ועוברים לאותה ספרייה בטרמינל.

התקנה והגדרה של `clasp`

אנחנו משתמשים ב- clasp כדי לערוך בקלות גרסאות של קוד המקור ולדחוף אותן מהסביבה המקומית לפרויקט Apps Script.

בסביבה המקומית, מתקינים את הגרסאות העדכניות של node, npm ו-clasp.

npm install -g @google/clasp

מתחברים לחשבון:

clasp login

אם הפעולה מצליחה, מופיע מסך אישור בסיסי בדפדפן האינטרנט, וקובץ .clasprc.json עם פרטי הכניסה של הלקוח מתעדכן. תוכלו לראות איפה הוא נמצא במסוף.

3. אפליקציה 1: בנייה

מושגים שכדאי להכיר

Vertex AI

‫Vertex AI מציעה את כל מה שצריך כדי ליצור ולהשתמש ב-AI גנרטיבי, כולל פתרונות AI, כלי ליצירת סוכנים, יותר מ-130 מודלים בסיסיים ופלטפורמת AI מאוחדת.

Gemini

‫Gemini הוא מודל שפה גדול (LLM) מרובה-מוֹדָלִים מבית Google, שאפשר לגשת אליו דרך Vertex AI. הוא עוזר לאנשים לממש את הפוטנציאל האנושי שלהם, כדי שיוכלו להרחיב את הדמיון, להגביר את הסקרנות ולשפר את הפרודוקטיביות.

שירות Chat מתקדם

שירות Advanced Chat מאפשר לכם להשתמש ב-Google Chat API ב-Apps Script. ההרשאה הזו מאפשרת לסקריפטים למצוא, ליצור ולשנות מרחבים ב-Chat, להוסיף או להסיר משתתפים במרחבים, ולקרוא או לפרסם הודעות עם טקסט, כרטיסים, קבצים מצורפים ותגובות.

בדיקת הארכיטקטורה

אפליקציית Google Chat הזו נוצרה באמצעות Apps Script. כך זה עובד:

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

בדיקת תהליכי עבודה

יצירת בעיה

פתרון בעיות ממרחב ייעודי

סגירת בעיה ממרחב ייעודי

בדיקת קוד המקור

פרויקט Apps Script מכיל את הסקריפטים הבאים:

‫Configuration: קבועים לעריכה בהתאם לסביבה.
‫ChatApp: מטפל באירועי אינטראקציה ב-Google Chat, כולל הודעות, קליקים על כרטיסים, פקודות עם קו נטוי ודיאלוגים.
‫Storage: פונקציות עזר שמסתמכות על שירותי מאפיינים.
ChatAppAuth: פונקציות שירות שמסתמכות על אימות של אפליקציית Google Chat.
‫Docs: פונקציות עזר שמסתמכות על Google Docs.
‫VertexAi: פונקציות עזר שמסתמכות על Vertex AI.

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

appsscript.json

// Enables the Admin SDK Directory and Chat services, which you need to retrieve
// messages and usernames.

"enabledAdvancedServices": [
  ...
  {
    "userSymbol": "AdminDirectory",
    "version": "directory_v1",
    "serviceId": "admin"
  },
  {
    "userSymbol": "Chat",
    "version": "v1",
    "serviceId": "chat"
  }
  ...
]

// Includes the OAuth scopes to request the Admin SDK Directory, Google Chat,
// Google Docs, and Vertex AI APIs.

"oauthScopes": [
  ...
  "https://www.googleapis.com/auth/admin.directory.user.readonly",
  "https://www.googleapis.com/auth/chat.messages.readonly",
  "https://www.googleapis.com/auth/documents",
  "https://www.googleapis.com/auth/cloud-platform",
  ...
]

Configuration.js

// Relies on two constants: the first one is the Google Cloud project ID and the
// second one is the Vertex AI location to be used.

...
const PROJECT_ID = 'replace-with-gcp-project-id';
const VERTEX_AI_LOCATION_ID = 'us-central1';
...

ChatApp.js

// The slash command process function retrieves history, generates content, and passes
// it to the report generator.

function processSlashCommand(event) {
  ...
  if (event.message.slashCommand.commandId == CLOSE_COMMAND_ID
    && event.message.space.type !== "DM") {
    ...
    const history = exportSpaceHistory(spaceId);
    const summary = summarizeSpace(history);
    const docUrl = createReport(
      issue.title, issue.description, resolution, history, summary
    );
    ...
  }
  ...
}

/**
 * Fetches and concatenates the 100 first space messages by using the Google Chat API.
 *
 * Messages with slash commands are filtered (app command invocations).
 *
 * @return {string} concatenate space messages in the format "Sender's name: Message"
 */
function exportSpaceHistory(spaceName) {
  const messages = Chat.Spaces.Messages.list(spaceName, { 'pageSize': 100 }).messages;
  // Returns results after fetching message sender display names.
  let users = new Map();
  return messages
    .filter(message => message.slashCommand === undefined)
    .map(message =>
      `${getUserDisplayName(users, message.sender.name)}: ${message.text}`
    ).join('\n');
}

/**
 * Fetches a user's display name by using the Admin Directory API.
 *
 * A cache is used to only call the API once per user.
 *
 * @param {Map} cache the map containing users previously fetched
 * @param {string} userId the user ID to fetch
 * @return {string} the user's display name
 */
function getUserDisplayName(cache, userId) {
  if (cache.has(userId)) {
    return cache.get(userId);
  }
  let displayName = 'Unknown User';
  try {
    const user = AdminDirectory.Users.get(
      userId.replace("users/", ""),
      { projection: 'BASIC', viewType: 'domain_public' });
    displayName = user.name.displayName ? user.name.displayName : user.name.fullName;
  } catch (e) {
    // Ignores errors, uses 'Unknown User' by default.
  }
  cache.set(userId, displayName);
  return displayName;
}

VertexAi.js

/**
 * Summarizes a Google Chat space history with the Gemini Pro model using
 * Vertex AI API.
 *
 * @param {string} history the history
 * @return {string} the summary
 */
function summarizeSpace(history) {
  const url = `https://${VERTEX_AI_LOCATION_ID}-aiplatform.googleapis.com/v1`
    + `/projects/${PROJECT_ID}/locations/${VERTEX_AI_LOCATION_ID}`
    + "/publishers/google/models/gemini-1.0-pro:generateContent";
  const options = {
    method: "POST",
    headers: { Authorization: "Bearer " + ScriptApp.getOAuthToken() },
    contentType: "application/json",
    payload: JSON.stringify({
      contents: {
        role: "user",
        parts: {
          text: "Summarize the following conversation between engineers resolving"
              + " an issue in a few sentences.\n\n" + history
        }
      },
      safetySettings: {
        category: "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        threshold: "BLOCK_LOW_AND_ABOVE"
      },
      generationConfig: {
        temperature: 0.2,
        topP: 0.8,
        topK: 40
      }
    })
  };

  return JSON.parse(UrlFetchApp.fetch(url, options).getContentText())
    .candidates[0].content.parts[0].text;
}

Docs.js

// The report generator function adds two sections: the first one is for the summary and the second one is for history.
function createReport(..., history, summary) {
  ...
  body.appendParagraph("Summary").setHeading(DocumentApp.ParagraphHeading.HEADING1);
  body.appendParagraph(summary);
  body.appendParagraph("History").setHeading(DocumentApp.ParagraphHeading.HEADING1);
  body.appendParagraph(history);
  ...
}

עדכון פרויקט ב-Google Cloud

הפעלת ממשקי API

ב-מסוף Google Cloud, מפעילים את ממשקי ה-API‏ Google Docs,‏ Google Admin SDK ו-Vertex AI:

לוחצים על Menu ☰ > APIs & Services (תפריט > ממשקי API ושירותים) > Enabled APIs & Services (ממשקי API ושירותים מופעלים) ומוודאים שממשקי ה-API מופעלים.

Initiate service account

במסוף Google Cloud, פועלים לפי השלבים הבאים:

לוחצים על תפריט ☰ > IAM & Admin > Service Accounts > + Create service account (תפריט ☰ > IAM ואדמין > חשבונות שירות > + יצירת חשבון שירות).

מגדירים את Service account name לערך chat-app.
מגדירים את תיאור חשבון השירות ל-Chat app auth.
לוחצים על יצירה והמשך.
לוחצים על סיום. תועברו לדף Service accounts ותוכלו לראות את חשבון השירות שיצרתם.

בוחרים את חשבון השירות החדש שנוצר.
לוחצים על הכרטיסייה Keys.
לוחצים על הוספת מפתח.
לוחצים על Create new key.
בוחרים באפשרות JSON.
לוחצים על יצירה.

תיבת הדו-שיח תיסגר וזוג המפתחות הציבורי/פרטי החדש שנוצר יורד אוטומטית לסביבה המקומית כקובץ JSON. משתמשים בתוכן שלו בהמשך כשעורכים את קוד המקור של פרויקט Apps Script.

עדכון ההגדרה של Google Chat API

במסוף Google Cloud, פועלים לפי השלבים הבאים:

מוסיפים פקודה דרך שורת הפקודות.
מגדירים את Name לערך /create.
מגדירים את מזהה הפקודה לערך 1.
מגדירים את Description לערך Create a new issue.
מסמנים את התיבה פתיחת תיבת דו-שיח.
מוסיפים עוד פקודה דרך שורת הפקודות.
מגדירים את Name לערך /close.
מגדירים את מזהה הפקודה לערך 2.
מגדירים את Description לערך Close an issue.
לוחצים על שמירה.

עדכון פרויקט Apps Script

משנים את הספרייה הנוכחית במסוף המקומי ל-issue-management/1-baseline. הוא מכיל את קוד המקור. לפני שמעבירים את קוד המקור לפרויקט Apps Script, צריך להגדיר כמה דברים.

הגדרת קוד המקור

מגדירים את הקבוע JSON שנקרא CHAT_CREDENTIALS בקובץ Configuration.js לתוכן של קובץ המפתח הפרטי שהורדתם קודם.

ב-מסוף Google Cloud, לוחצים על תפריט ☰ > IAM & Admin > Settings (תפריט ☰ > IAM ומנהל מערכת > הגדרות).

מעתיקים את מזהה הפרויקט.

מגדירים את הקבוע מסוג מחרוזת בשם PROJECT_ID בקובץ Configuration.js למזהה הפרויקט.

הגדרה של `clasp` הגדרות

כדי לאתחל את ההגדרות של clasp כדי לדחוף את קוד המקור לפרויקט הנכון של Apps Script, פועלים לפי השלבים הבאים:

ב-Apps Script console, בוחרים את הפרויקט.
בוחרים באפשרות Project Settings (הגדרות הפרויקט).
בקטע מזהים, לוחצים על העתקה.

בספרייה הנוכחית, יוצרים קובץ .clasp.json.
מחליפים את <your-script-id> במזהה שהעתקתם.
מעתיקים את התוצאה לקובץ .clasp.json.
שומרים את קובץ ה-.clasp.json.

{
  "scriptId": "<your-script-id>"
}

העברת קוד המקור

מריצים את הפקודה הבאה:

$clasp push
? Manifest file has been updated. Do you want to push and overwrite? Yes
└─ appsscript.json
└─ ChatApp.js
└─ ChatAppAuth.js
└─ Configuration.js
└─ Docs.js
└─ Storage.js
└─ VertexAi.js
Pushed 7 files.

אני רוצה לנסות אותו

ב-Google Chat, שולחים את Hello! בצ'אט ישיר לאפליקציה. האפליקציה לא משיבה, אבל מופיעה הודעה שמבקשת להגדיר את האפליקציה.

לוחצים על הגדרה.
בוחרים את חשבון Google.
מבצעים אימות.
בודקים ומאשרים את הגישה לאפליקציה.

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

שולחים לאפליקציה הודעה נוספת בצ'אט ישיר, אבל עם הפקודה דרך שורת הפקודות /create.

בתיבת הדו-שיח, מגדירים את הכותרת ל-Issue Title 1.
מגדירים את Description (תיאור) ל-Issue Description 1 (בעיה).
לוחצים על יצירה.

האפליקציה מבצעת את הפעולות הבאות:

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

במרחב החדש שנוצר, שולחים הודעה עם פקודת הלוכסן /close והרזולוציה, למשל Not reproducible.

האפליקציה מבצעת את הפעולות הבאות:

יוצר מסמך דוח ב-Google Docs.
המערכת שולחת הודעה למרחב שמוקדש לבעיה עם קישור למסמך הדוח שנוצר.

פותחים את מסמך הדוח. היא מכילה מידע בסיסי, היסטוריה וסיכום.

4. אופציונלי: אפליקציה 1: הוספת דף הבית של האפליקציה

מושגים שכדאי להכיר

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

בדיקת תהליכי עבודה

ניהול בעיות

בדיקת קוד המקור

צריך לערוך את פרויקט Apps Script.

ChatApp.js

/**
 * Handles app home requests in Google Chat.
 * 
 * Displays the latest status of all issues.
 */
function onAppHome() {
  // Generates one card section per issue.
  var sections = [];
  for (var issueKey in appProperties.getProperties()) {
    const issue = JSON.parse(appProperties.getProperty(issueKey));
    if (issue.spaceId) {
      sections.push({
        header: `${issue.status} - ${issue.title}`,
        widgets: [{ textParagraph: {
            text: `Description: ${issue.description}`
          }}, { textParagraph: {
            text: `Resolution: ${issue.resolution}`
          }}, { buttonList: { buttons: [{
              text: "Open space",
              onClick: { openLink: {
                url: `https://mail.google.com/mail/u/0/#chat/space/${issue.spaceId}`
              }}
            }, {
              text: "Open report",
              onClick: { openLink: {
                url: issue.reportUrl !== "" ? issue.reportUrl : "docs.new"
              }},
              disabled: issue.reportUrl === ""
          }]}
        }]
      });
    }
  }

  return { action: { navigations: [{ push_card: {
    sections: sections
  }}]}};
}

עדכון פרויקט ב-Google Cloud

במסוף Google Cloud, פועלים לפי השלבים הבאים:

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

בסביבה המקומית, פועלים לפי השלבים הבאים:

משנים את הספרייה הנוכחית במסוף ל-issue-management/2-app-home. הוא מכיל את קוד המקור שבו צריך להשתמש.
מעתיקים את הקובץ issue-management/1-baseline/.clasp.json לספרייה הנוכחית.
מעתיקים את הקובץ issue-management/1-baseline/Configuration.js לספרייה הנוכחית כדי להחליף את הקובץ הקיים.
מריצים את הפקודה הבאה:

clasp push

אני רוצה לנסות

ב-Google Chat, פועלים לפי השלבים הבאים:

שולחים לאפליקציה הודעה בצ'אט ישיר עם פקודה דרך שורת הפקודות /create. האפליקציה פותחת תיבת דו-שיח.
מגדירים את Title לערך Issue Title 2.
מגדירים את Description (תיאור) ל-Issue Description 2 (בעיה).
לוחצים על יצירה.

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

5. אופציונלי: אפליקציה 1: הוספת מעקב אחר המרחב

בדיקת מושגים

Pub/Sub

‫Pub/Sub הוא שירות העברת הודעות אסינכרוני וניתן להרחבה, שמפריד בין שירותים שמפיקים הודעות לבין שירותים שמעבדים את ההודעות האלה. ‫Pub/Sub מאפשר ליצור מערכות של יצרני אירועים וצרכני אירועים, שנקראים אפליקציות לשליחת הודעות ואפליקציות רשומות. בעלי האתרים מתקשרים עם המנויים באופן אסינכרוני על ידי שידור אירועים, ולא על ידי קריאות פרוצדורה מרוחקות (RPC) סינכרוניות.

בעלי אתרים שולחים אירועים לשירות Pub/Sub בלי להתייחס לאופן שבו האירועים האלה יעובדו או למועד העיבוד שלהם. לאחר מכן, שירות Pub/Sub מעביר את האירועים לכל השירותים שמגיבים להם. במערכות שמתקשרות באמצעות RPC, בעלי תוכן דיגיטלי צריכים לחכות עד שהמנויים יקבלו את הנתונים. עם זאת, השילוב האסינכרוני ב-Pub/Sub מגדיל את הגמישות והיציבות של המערכת הכוללת.

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

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

אירועים ב-Google Workspace

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

כך Google Workspace Events API מעביר אירועים לאפליקציה באמצעות מינוי:

האפליקציה נרשמת למשאב באפליקציית Google Workspace, כמו מרחב.
המשאב שאליו האפליקציה נרשמה משתנה.
אפליקציית Google Workspace מעבירה אירוע לנושא ב-Pub/Sub, שמשמש כנקודת הקצה של ההתראות למינוי ל-Google Workspace של האפליקציה. האירוע מכיל נתונים על השינויים שבוצעו במשאב.
האפליקציה מעבדת את ההודעה ב-Pub/Sub שמכילה את האירוע, ואם צריך, מבצעת פעולה.

בדיקת תהליכי עבודה

יצירת בעיה (עדכון)

פתרון בעיה ממרחב ייעודי (עדכון)

סגירת בעיה ממרחב ייעודי (עדכון)

עיבוד מינויים

בדיקת קוד המקור

צריך לערוך את פרויקט Apps Script.

appsscript.json

// Enables the Workspace Events service.

"enabledAdvancedServices": [
  ...
  {
    "userSymbol": "WorkspaceEvents",
    "version": "v1",
    "serviceId": "workspaceevents"
  }
  ...
]

Configuration.js

// Adds two constants: the first one is the Pub/Sub topic ID and the second one
// is the Pub/Sub subscription ID to be used to retrieve Google Workspace events.

...
const GWS_PUBSUB_TOPIC_ID = `projects/${PROJECT_ID}/topics/workspace-events`;
const GWS_PUBSUB_SUBSCRIPTION_ID =
  `projects/${PROJECT_ID}/subscriptions/workspace-events-sub`;
...

ChatApp.js

// Edits the function to delete the subscription at issue closure.

function processSlashCommand(event) {
  ...
  if (event.message.slashCommand.commandId == CLOSE_COMMAND_ID
    && event.message.space.type !== "DM") {
    ...
    deleteSubscription(issue.subscriptionId);
    ...
  }
  ...
}

// Edits the function to create the subscription.

function createIssue(event) {
  ...
  const subscriptionId = createSpaceSubscription(spaceUrl);
  const createdIssue = saveCreatedIssue(..., subscriptionId);
  ...
}

// Edits the function to delete the subscription.

function onRemoveFromSpace(event) {
  ...
  deleteSubscription(issue.subscriptionId);
  ...
}

Storage.js

// Edits the function to keep track of the subscription ID.

function saveCreatedIssue(..., spaceId, subscriptionId) {
  ...
  appProperties.setProperty(spaceId, JSON.stringify({
    ...
    subscriptionId: subscriptionId,
    ...
  }));
  ...
}

WorkspaceEvent.js

/**
 * Creates a new subscription to Google Workspace Events associated to a
 * Google Chat space.
 * 
 * The subscription scope includes message creation events and resources.
 * 
 * @param {string} spaceId the space ID to create a subscription for
 * @return the ID of the newly created subscription
 */
function createSpaceSubscription(spaceId) {
  const operation = WorkspaceEvents.Subscriptions.create({
    targetResource: `//chat.googleapis.com/${spaceId}`,
    eventTypes: ["google.workspace.chat.message.v1.created"],
    notificationEndpoint: { pubsubTopic: GWS_PUBSUB_TOPIC_ID },
    payloadOptions: { includeResource: true },
  });

  return operation.response.name;
}

/**
 * Processes events from subscription by using the Google Cloud PubSub API.
 * 
 * It pulls and acknowledges each event.
 */
function processSubscription() {
  const response = UrlFetchApp.fetch(
    `https://pubsub.googleapis.com/v1/${GWS_PUBSUB_SUBSCRIPTION_ID}:pull`,
    {
      method: "POST",
      contentType: "application/json",
      headers: { "Authorization": "Bearer " + ScriptApp.getOAuthToken() },
      payload: JSON.stringify({ maxMessages: 10 })
    }
  );

  const messages = JSON.parse(response.getContentText()).receivedMessages;
  for (var messageIndex in messages) {
    const message = messages[messageIndex];
    const ceType = message.message.attributes["ce-type"];
    const dataStr = Utilities.newBlob(Utilities.base64Decode(message.message.data))
      .getDataAsString();
    if (ceType === "google.workspace.events.subscription.v1.expirationReminder") {
      // Renews subscription.
      renewSubscription(JSON.parse(dataStr).subscription.name);
    } else if (ceType === "google.workspace.chat.message.v1.created") {
      // Processes the message text when it's sent in a space.
      const chatMessage = JSON.parse(dataStr).message;
      if (chatMessage.sender.type !== "BOT") {
        console.log("Message was processed.");
      }
    }
    // Acknowledges successful processing to avoid getting it again next time.
    ackSubscription(message.ackId);
  }
}

/**
 * Acknowledges a subscription event by using the Google Cloud PubSub API.
 * 
 * @param {string} ackId the ID of the event acknowledgment to send
 */
function ackSubscription(ackId) {
  UrlFetchApp.fetch(
    `https://pubsub.googleapis.com/v1/${GWS_PUBSUB_SUBSCRIPTION_ID}:acknowledge`,
    {
      method: "POST",
      contentType: "application/json",
      headers: { "Authorization": "Bearer " + ScriptApp.getOAuthToken() },
      payload: JSON.stringify({
        ackIds: [ackId]
      })
    }
  );
}

/**
 * Renews a subscription to Google Workspace Events.
 * 
 * The default time to live option is used.
 * 
 * @param {string} subscriptionId the ID of the subscription to renew
 */
function renewSubscription(subscriptionId) {
  WorkspaceEvents.Subscriptions.patch({ttl: '0s'}, subscriptionId);
}

/**
 * Deletes a subscription to Google Workspace Events.
 * 
 * @param {string} subscriptionId the ID of the subscription to delete
 */
function deleteSubscription(subscriptionId) {
  WorkspaceEvents.Subscriptions.remove(subscriptionId);
}

עדכון פרויקט ב-Google Cloud

הפעלת ממשקי API

במסוף Google Cloud, מפעילים את Google Workspace Events ואת PubSub.

לוחצים על תפריט ☰ > ממשקי API ושירותים > ממשקי API ושירותים מופעלים ומוודאים ששניהם מופעלים.

הפעלת מינוי

כדי שכל האירועים במרחב העבודה יפורסמו, צריך ליצור נושא Pub/Sub ולהירשם אליו.

במסוף Google Cloud, פועלים לפי השלבים הבאים:

עוברים אל תפריט ☰ > Pub/Sub > נושאים.

לוחצים על יצירת נושא.
מגדירים את Topic ID (מזהה הנושא) לערך workspace-events.
מסמנים את התיבה הוספת מינוי שמוגדר כברירת מחדל.
לוחצים על יצירה.

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

בוחרים את הנושא מהרשימה.
לוחצים על הכרטיסייה הרשאות.
מוסיפים את chat-api-push@system.gserviceaccount.com אל New principals.
בוחרים באפשרות Pub/Sub Publisher (פרסום הודעות ב-Pub/Sub) בשדה Role (תפקיד).
לוחצים על שמירה.

עדכון פרויקט Apps Script

במסוף Google Cloud, פועלים לפי השלבים הבאים:

עוברים אל תפריט ☰ > IAM & Admin > Settings (ניהול הרשאות גישה ואדמין > הגדרות).

מעתיקים את מזהה הפרויקט.

בסביבה המקומית, פועלים לפי השלבים הבאים:

משנים את הספרייה הנוכחית במסוף ל-issue-management/3-message-monitoring. הוא מכיל את קוד המקור שאתם צריכים.
מגדירים את הקבוע המחרוזתי בשם PROJECT_ID בקובץ Configuration.js למזהה הפרויקט שהועתק.
מגדירים את הקבוע JSON שנקרא CHAT_CREDENTIALS בקובץ Configuration.js לתוכן של קובץ המפתח הפרטי שהורדתם קודם.
מעתיקים את הקובץ issue-management/2-app-home/.clasp.json לספרייה הנוכחית.
מריצים את הפקודה הבאה:

clasp push

אני רוצה לנסות

ב-Google Chat, פועלים לפי השלבים הבאים:

שולחים לאפליקציה הודעה בצ'אט ישיר עם פקודה דרך שורת הפקודות /create. האפליקציה פותחת תיבת דו-שיח.
מגדירים את Title לערך Issue Title 3.
מגדירים את Description (תיאור) ל-Issue Description 3 (בעיה).
לוחצים על יצירה.
במרחב החדש שנוצר, שולחים כמה הודעות שבהן דנים בבעיה.
שולחים הודעה עם פקודה דרך שורת הפקודות /close ורזולוציה כמו Fixed.

במסוף Google Cloud, פועלים לפי השלבים הבאים:

עוברים אל תפריט ☰ > Pub/Sub > מינויים.

בוחרים את המינוי workspace-events-sub.
לוחצים על הכרטיסייה הודעות.
לוחצים על Pull (משיכה). בטבלה מוצגות ההודעות שקשורות למה ששלחתם למרחב החדש.

ב-Apps Script console, פועלים לפי השלבים הבאים:

בוחרים את הפרויקט הרצוי.
לוחצים על עריכה.
בוחרים את הקובץ WorkspaceEvent.gs.
בקטע Run, בוחרים באפשרות processSubscription.
לוחצים על Run.אפשר לראות ביומן הביצוע שההודעות עברו עיבוד.

במסוף Google Cloud, פועלים לפי השלבים הבאים:

עוברים אל תפריט ☰ > Pub/Sub > מינויים.

בוחרים את המינוי workspace-events-sub.
לוחצים על הכרטיסייה הודעות.
לוחצים על Pull (משיכה). ההודעות שקשורות למה ששלחתם למרחב החדש לא מוצגות יותר בטבלה.

במרחב שמוקדש לבעיה השלישית שיצרתם באמצעות פקודה דרך שורת הפקודות /create ב-Google Chat, שולחים עוד כמה הודעות שמתייחסות לבעיה.

במסוף Google Cloud, פועלים לפי השלבים הבאים:

עוברים אל תפריט ☰ > Pub/Sub > מינויים.

בוחרים את המינוי workspace-events-sub.
לוחצים על הכרטיסייה הודעות.
לוחצים על Pull (משיכה). בטבלה לא מוצגות ההודעות שקשורות למה ששלחתם למרחב החדש.

6. אופציונלי: אפליקציה 1: הוספת עזרה בנושא קבלת האחר

בדיקת מושגים

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

בדיקת תהליכי עבודה

עיבוד מינויים (עדכון)

בדיקת קוד המקור

צריך לערוך את פרויקט Apps Script.

WorkspaceEvent.js

// Edits the function to replace logging by an actual card message.

function processSubscription() {
  ...
  for (var messageIndex in messages) {
    ...
    } else if (ceType === "google.workspace.chat.message.v1.created") {
      ...
      const inclusivityCheck = getInclusivityFeedback(chatMessage.text);
      if (inclusivityCheck !== "It's inclusive!") {
        createAppMessageUsingChatService({
          cardsV2: [{ cardId: "1", card: { header: {
              title: "Inclusivity",
              subtitle: `The following words are not inclusive: ${inclusivityCheck}`
          }}}]
        },
        chatMessage.space.name);
      }
      ...
    }
    ...
  }
  ...
}

VertexAi.js

/**
 * Gets feedback on inclusivity for a text with the Gemini Pro model using
 * Vertex AI API.
 * 
 * Returns "It's inclusive!" when it is otherwise a list of word(s) that might not
 * be optimal.
 *
 * @param {string} text the text
 * @return {string} the feedback
 */
function getInclusivityFeedback(text) {
  const url = `https://${VERTEX_AI_LOCATION_ID}-aiplatform.googleapis.com/v1`
    + `/projects/${PROJECT_ID}/locations/${VERTEX_AI_LOCATION_ID}`
    + "/publishers/google/models/gemini-1.0-pro:generateContent";
  const options =  {
    method: "POST",
    headers: { Authorization: "Bearer " + ScriptApp.getOAuthToken() },
    contentType: "application/json",
    payload: JSON.stringify({
      contents: {
        role: "user",
        parts: {
          text: "Are there any words that obviously go against inclusivity "
            + "in this text:"
            + `\n\n----------\n${text}\n----------\n\n`
            + "If there are not, answer \"It's inclusive!\" "
            + "otherwise answer by listing them separated by commas. "
            + "Do not answer with any explanation."
        }
      },
      safetySettings: {
        category: "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        threshold: "BLOCK_LOW_AND_ABOVE"
      },
      generationConfig: {
        temperature: 0.2,
        topP: 0.8,
        topK: 40
      }
    })
  };

  return JSON.parse(UrlFetchApp.fetch(url, options).getContentText())
    .candidates[0].content.parts[0].text;
}

עדכון פרויקט Apps Script

בסביבה המקומית, פועלים לפי השלבים הבאים:

משנים את הספרייה הנוכחית בטרמינל ל-issue-management/4-inclusivity-help. הוא מכיל את קוד המקור שאתם צריכים.
מעתיקים את הקובץ issue-management/3-message-monitoring/.clasp.json לספרייה הנוכחית.
מעתיקים את הקובץ issue-management/3-message-monitoring/Configuration.js לספרייה הנוכחית כדי להחליף את הקובץ הקיים.
מריצים את הפקודה הבאה:

clasp push

אני רוצה לנסות

ב-Google Chat, פועלים לפי השלבים הבאים:

שולחים לאפליקציה הודעה בצ'אט ישיר עם פקודה דרך שורת הפקודות /create. האפליקציה פותחת תיבת דו-שיח.
מגדירים את Title לערך Issue Title 4.
מגדירים את Description (תיאור) ל-Issue Description 4 (בעיה).
לוחצים על יצירה.
במרחב החדש שנוצר, שולחים את ההודעה It happened to me last week as well.

ב-Apps Script console, פועלים לפי השלבים הבאים:

בוחרים את הפרויקט הרצוי.
לוחצים על עריכה.
בוחרים את הקובץ WorkspaceEvent.gs.
בקטע Run, בוחרים באפשרות processSubscription.
לוחצים על Run. אפשר לראות מיומן הביצוע שההודעות עברו עיבוד.

ב-Google Chat, פועלים לפי השלבים הבאים:

שימו לב שהאפליקציה לא שלחה עזרה בנושא שפה מכלילה במרחב החדש שנוצר.
במרחב החדש שנוצר, שולחים את ההודעה I had to add myself from the master to fix it.

ב-Apps Script console, פועלים לפי השלבים הבאים:

בוחרים את הפרויקט הרצוי.
לוחצים על עריכה.
בוחרים את הקובץ WorkspaceEvent.gs.
בקטע Run, בוחרים באפשרות processSubscription.
לוחצים על Run. אפשר לראות מיומן הביצוע שההודעות עברו עיבוד. ב-Google Chat, האפליקציה שלחה הודעה עם עזרה בנושא שילוב במרחב החדש שנוצר.

7. אופציונלי: אפליקציה 1: הוספת העדפות

בדיקת מושגים

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

בדיקת תהליכי עבודה

השבתת העזרה בנושא שפה מכלילה

בדיקת קוד המקור

צריך לערוך את פרויקט Apps Script.

ChatApp.js

// Edits the function to handle the inclusivity help disablement action for a
// given space.

function onCardClick(event) {
  ...
  if (event.action.actionMethodName === "disableInclusivityHelp") {
    disableInclusivityHelp(event.common.parameters.spaceId);
  }
}

Storage.js

// Edits the function to keep track of the inclusivity help setting.

function saveCreatedIssue(title, description, spaceId, subscriptionId) {
  appProperties.setProperty(spaceId, JSON.stringify({
    ...
    inclusivityHelp: true,
    ...
  }));
  ...
}

/**
 * Disables inclusivity help in a space.
 * 
 * @param {string} spaceId the ID of dedicated space of the issue
 */
function disableInclusivityHelp(spaceId) {
  var issue = JSON.parse(appProperties.getProperty(spaceId));
  issue.inclusivityHelp = false;
  appProperties.setProperty(spaceId, JSON.stringify(issue));
}

/**
 * Checks whether the app should help with inclusivity in a given space.
 * 
 * @param {string} spaceId the ID of dedicated space of the issue
 * @return whether the app should help with inclusivity
 */
function shouldHelpWithInclusivity(spaceId) {
  return JSON.parse(appProperties.getProperty(spaceId)).inclusivityHelp;
}

WorkspaceEvent.js

// Edits the function to display the accessory widget to the existing card message.

function processSubscription() {
  ...
  for (var messageIndex in messages) {
    ...
    } else if (ceType === "google.workspace.chat.message.v1.created") {
      ...
      if (... && shouldHelpWithInclusivity(chatMessage.space.name)) {
        createAppMessageUsingChatService({
          ...
          accessoryWidgets: [{ buttonList: { buttons: [{
            altText: "Disable inclusivity help",
            icon: {
              iconUrl: "https://upload.wikimedia.org/.../Stop_hand_rugen.png"
            },
            onClick: { action: {
              function: "disableInclusivityHelp",
              parameters: [{
                key: "spaceId",
                value: chatMessage.space.name
              }]
            }}
          }]}}]
        }, ...);
        ...
      }
      ...
    }
    ...
  }
  ...
}

עדכון פרויקט Apps Script

בסביבה המקומית, פועלים לפי השלבים הבאים:

משנים את הספרייה הנוכחית במסוף ל-issue-management/5-disable-help. הוא מכיל את קוד המקור שאתם צריכים.
מעתיקים את הקובץ issue-management/4-inclusivity-help/.clasp.json לספרייה הנוכחית.
מעתיקים את הקובץ issue-management/4-inclusivity-help/Configuration.js לספרייה הנוכחית כדי להחליף את הקובץ הקיים.
מריצים את הפקודה הבאה:

clasp push

אני רוצה לנסות

השבתת העזרה

ב-Google Chat, במרחב שמוקדש לבעיה הרביעית שיצרתם באמצעות פקודה דרך שורת הפקודות /create, שולחים את ההודעה I had to add myself from the master to fix.

ב-Apps Script console, פועלים לפי השלבים הבאים:

בוחרים את הפרויקט הרצוי.
לוחצים על עריכה.
בוחרים את הקובץ WorkspaceEvent.gs.
בקטע Run, בוחרים באפשרות processSubscription.
לוחצים על Run. אפשר לראות מיומן הביצוע שההודעות עברו עיבוד.

ב-Google Chat, פועלים לפי השלבים הבאים:

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

בדיקת השבתה

ב-Google Chat, במרחב שמוקדש לבעיה הרביעית שיצרתם באמצעות פקודה דרך שורת הפקודות /create, שולחים את ההודעה I had to add myself from the master to fix.

ב-Apps Script console, פועלים לפי השלבים הבאים:

בוחרים את הפרויקט הרצוי.
לוחצים על עריכה.
בוחרים את הקובץ WorkspaceEvent.gs.
בקטע Run, בוחרים באפשרות processSubscription.
לוחצים על Run. אפשר לראות מיומן הביצוע שההודעות עברו עיבוד. ב-Google Chat, האפליקציה לא שלחה הודעה עם עזרה בנושא שפה מכלילה למרחב שמוקדש לבעיה כי היא הושבתה.

8. אפליקציה 2: Build

מושגים שכדאי להכיר

הארקה של AI גנרטיבי

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

שפה טבעית

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

Cloud Storage

באמצעות Cloud Storage אתם יכולים לאחסן נתונים בכל העולם ולאחזר כל כמות של נתונים בכל זמן. אפשר להשתמש בו למגוון תרחישים, כולל מילוי בקשה לתוכן של אתר, אחסון נתונים להעברה לארכיון ולתוכנית התאוששות מאסון (DR), או כדי להפיץ אובייקטים גדולים של נתונים למשתמשים באמצעות הורדה ישירה.

מאגר נתונים של Dialogflow CX

‫Dialogflow CX משתלב עם מאגרי נתונים שהם אוספים של אתרים ומסמכים שמשמשים סוכני מאגרי נתונים כדי למצוא תשובות לשאלות של משתמשי קצה מנתונים ספציפיים. לכל שאלה, הנציג של מאגר הנתונים מחפש תשובה בתוכן המקור שצוין ומסכם את הממצאים לתשובה עקבית. הוא גם מספק קישורים למקורות המידע שעליהם התבססה התשובה, כדי שמשתמש הקצה יוכל לקבל מידע נוסף.

בדיקת הארכיטקטורה

אפליקציית Google Chat הזו מבוססת על Dialogflow CX ופועלת באופן הבא:

משתמש שולח הודעה לאפליקציה, בצ'אט ישיר או במרחב.
האפליקציה, שהיא סוכן Dialogflow CX ומשויכת לפרויקט בענן של Google, מעבדת את ההודעה.
האפליקציה משולבת עם מאגר נתונים שנמצא ב-Cloud Storage.
האפליקציה שולחת תגובה סינכרונית, בצ'אט ישיר או במרחב המקורי.

בדיקת תהליכים

הוספת תשובה לשאלה

בדיקת קוד המקור

המקור היחיד שאתם צריכים הוא לא קוד, אלא נתונים שמשמשים להארקה.

google-chat-overview.pdf

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

עדכון פרויקט בענן ב-Google Cloud

במסוף Google Cloud, פועלים לפי השלבים הבאים:

מפעילים את Dialogflow API ואת Cloud Storage API.

מפעילים את Vertex AI Agent Builder API.

לוחצים על תפריט ☰ > ממשקי API ושירותים > ממשקי API ושירותים מופעלים ומוודאים שכל ממשקי ה-API מופעלים.

יצירת סוכן מאגר נתונים ב-Dialogflow CX

הפעלת נתוני ידע

במסוף Google Cloud, פועלים לפי השלבים הבאים:

לוחצים על תפריט ☰ > Cloud Storage > Buckets.

לוחצים על יצירה.
מגדירים את name לערך gchat-knowledge.
לוחצים על יצירה.

בוחרים בדלי gchat-knowledge.
לוחצים על Upload files.
מורידים את הקובץ google-chat-overview.pdf מהסביבה המקומית ובוחרים אותו.

יצירת אפליקציה

במסוף Google Cloud, פועלים לפי השלבים הבאים:

לוחצים על תפריט ☰ > הכלי ליצירת סוכנים > אפליקציות.

לוחצים על אפליקציה חדשה.
בוחרים את סוג הצ'אט.

מגדירים את Company name לשם החברה.
מגדירים את Agent name לערך knowledge.
לוחצים על המשך.

לוחצים על יצירת מאגר נתונים חדש.
בוחרים ב-Cloud Storage כמקור הנתונים.

בוחרים באפשרות קובץ.
לוחצים על מה מעניין אותך היום?
בוחרים את הקובץ google-chat-overview.pdf.
לוחצים על המשך.
מגדירים את שם מאגר הנתונים ל-gchat-knowledge-ds.
לוחצים על יצירה.

בוחרים את מאגר הנתונים gchat-knowledge-ds בטבלה.
לוחצים על יצירה.

אחרי כמה דקות, לוחצים על תפריט ☰ > הכלי ליצירת סוכנים > אפליקציות ורואים שהאפליקציה מופיעה.

לוחצים על תפריט ☰ > הכלי ליצירת סוכנים > מאגרי נתונים.

לוחצים על מאגר הנתונים gchat-knowledge-ds. מספר המסמכים הוא 1, מה שמצביע על כך שהמסמך מוכן.

השלמת האפליקציה ובדיקתה

ב-Dialogflow CX console, פועלים לפי השלבים הבאים:

בוחרים את הפרויקט בענן ב-Google Cloud.
בוחרים את סוכן הידע.

בוחרים באפשרות הגדרות סוכן > AI גנרטיבי > סוכן גנרטיבי.
מחליפים את המודל מ-Text Bison ל-Gemini Pro.
לוחצים על שמירה.

לוחצים על בדיקת הסוכן.
שליחה של What is Google Chat?. הנציג עונה עם משהו משמעותי.

שילוב אפליקציית Google Chat

ב-Dialogflow CX console, פועלים לפי השלבים הבאים:

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

במסוף Google Cloud, פועלים לפי השלבים הבאים:

עוברים להגדרות של Google Chat API.

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

ב-Google Chat, שולחים את What is Google Chat? בצ'אט ישיר לאפליקציית Google Chat. הסוכן מגיב עם משהו משמעותי.

9. אופציונלי: אפליקציה 2: הוספת מקורות

מושגים שכדאי להכיר

Dialogflow CX webhook

שירות שמארח לוגיקה עסקית או קורא לשירותים אחרים. במהלך סשן של Dialogflow CX, אפשר להשתמש ב-webhooks כדי להסתמך על הנתונים שחולצו על ידי עיבוד שפה טבעית (NLP) כדי ליצור תגובות דינמיות, לאמת נתונים שנאספו או להפעיל פעולות ב-backend.

Cloud Functions

‫Cloud Functions מצוין לפיתוח קצה עורפי ללא שרת (serverless), לעיבוד נתונים בזמן אמת וליצירת אפליקציות חכמות. אין שרתים שצריך להקצות, לנהל, לתקן או לעדכן. הם מתרחבים אוטומטית, ויש להם זמינות גבוהה ועמידות בכשלים.

בדיקת תהליכים

מענה על שאלה (עדכון)

בדיקת קוד המקור

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

package.json

// The function relies on the Cloud Functions framework to run.

{
  "name": "agent-response-adapter",
  "version": "0.0.1",
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  },
  ...
}

index.js

/** 
 * Handles all incoming requests.
 *
 * It takes a Dialogflow CX agent response as input and returns a
 * valid Google Chat card message with both the text and source links
 */
functions.http('agent-response-adapter', (request, response) => {
  // Creates Google Chat buttons based on the data store agent response
  // grounding details.
  var linkTitles = [];
  var linkButtons = [];
  const grounding = request.body.messages[1].payload.richContent[0][0];
  if (grounding.type === "match_citations") {
    // Supports citation match type.
    grounding.citations.forEach((citation) => {
      // Avoid duplications.
      if (linkTitles.indexOf(citation.title) < 0) {
        linkButtons.push({
          text: citation.title,
          onClick: { openLink: {
            url: citation.actionLink
          }}
        });
        linkTitles.push(citation.title);
      }
    });
  } else if (grounding.type === "info") {
    // Supports info type.
    if (linkTitles.indexOf(grounding.title) < 0) {
      linkButtons.push({
        text: grounding.title,
        onClick: { openLink: {
          url: grounding.actionLink
        }}
      });
      linkTitles.push(grounding.title);
    }
  }

  // Sends the Dialogflow CX fulfillment response to replace the agent response
  // with the Chat message with text and source buttons.
  response.send({ fulfillment_response: {
    merge_behavior: "REPLACE",
    messages: [{ payload: {
      // Reuses the original data store agent response text.
      text: request.body.messages[0].text.text[0],
      cardsV2: [{
        cardId: "sourcesCard",
        card: { sections: [{
          header: "Sources",
          widgets: [{ buttonList: {
            buttons: linkButtons
          }}]
        }]}
      }]
    }}]
  }});
});

עדכון פרויקט ב-Google Cloud

במסוף Google Cloud, פועלים לפי השלבים הבאים:

מפעילים את Cloud Build API,‏ Cloud Functions API,‏ Cloud Logging API,‏ Artifact Registry API ו-Cloud Run API.

לוחצים על Menu ☰ > APIs & services > Enabled APIs & services ומוודאים שממשקי ה-API מופעלים.

עדכון סוכן מאגר נתונים ב-Dialogflow CX

צריך לפרוס פונקציה ב-Cloud Functions ולעדכן את ה-webhook של Dialogflow CX כדי להפעיל אותה עם כמה מקורות, כשזה אפשרי.

החזרת כמה מקורות

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

ב-Dialogflow CX console, פועלים לפי השלבים הבאים:

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

הפעלת פונקציה של Cloud Functions

במסוף Google Cloud, פועלים לפי השלבים הבאים:

לוחצים על תפריט ☰ > Cloud Functions.

לוחצים על יצירת פונקציה.
בקטע Basics, מגדירים את name לערך function-1.
בקטע אימות, בוחרים בלחצן האפשרויות התרת הפעלות לא מאומתות.
בקטע Runtime, build, connections and security settings (הגדרות של זמן ריצה, build, חיבורים ואבטחה), מגדירים את Maximum number of instances (מספר המופעים המקסימלי) ל-3.
לוחצים על הבא.

מגדירים את Entry point ל-agent-response-adapter.
מחליפים את תוכן ברירת המחדל בקבצים package.json ו-index.js.
לוחצים על פריסה.

מעתיקים את כתובת ה-URL וממתינים כמה דקות עד שהפונקציה תופעל.

הפעלת webhook

צריך להגדיר את סוכן Dialogflow CX כך שישתמש ב-webhook שמפעיל את הפונקציה החדשה שפרסתם.

ב-Dialogflow CX console, פועלים לפי השלבים הבאים:

בוחרים את הפרויקט בענן ב-Google Cloud.
בוחרים את סוכן הידע.
בוחרים באפשרות ניהול > Webhooks > יצירה.
מגדירים את השם המוצג לערך Google Chat Response Adapter.
מגדירים את כתובת ה-URL של ה-Webhook לכתובת ה-URL שהעתקתם קודם.
לוחצים על שמירה.

לוחצים על Build.
בוחרים באפשרות דף הפתיחה.
בוחרים באפשרות עריכת מאגרי נתונים.
בקטע Webhook settings (הגדרות webhook), לוחצים על המתג Enable webhook (הפעלת webhook).
בוחרים באפשרות Google Chat Response Adapter for Webhook (מתאם תגובה של Google Chat ל-Webhook).
מגדירים את tag לערך arbitrary_tag.
לוחצים על שמירה.

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

ב-Google Chat, שולחים את What is Google Chat? בצ'אט ישיר לאפליקציית Google Chat. ה-Agent משיב עם משהו משמעותי וכרטיס עם מקורות, אם יש כאלה.

10. אפליקציה 3: Build

מושגים שכדאי להכיר

אינטראקציות שיחה

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

מפרט OpenAPI

היא מספקת אמצעי עקבי להעברת מידע בכל שלב במחזור החיים של ה-API. זו שפת מפרט לממשקי HTTP API שמגדירה מבנה ותחביר באופן שלא תלוי בשפת התכנות שבה נוצר ה-API. מפרטי API נכתבים בדרך כלל ב-YAML או ב-JSON, מה שמאפשר שיתוף ושימוש קלים במפרט.

סוכן Dialogflow CX

אבן הבניין הבסיסית של אפליקציות סוכנים. אפליקציית סוכנים כוללת בדרך כלל הרבה סוכנים, וכל סוכן מוגדר לטפל במשימות ספציפיות. נתוני הסוכן מסופקים ל-LLM, כדי שיהיה לו את המידע שהוא צריך כדי לענות על שאלות ולבצע משימות. כל סוכן יכול לספק מידע, לשלוח שאילתות לשירותים חיצוניים או להעביר את הטיפול בשיחה לזרימת עבודה של Dialogflow CX או לסוכן אחר כדי לטפל במשימות משנה.

הכלי Dialogflow CX

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

בדיקת הארכיטקטורה

אפליקציית Google Chat הזו מבוססת על Dialogflow CX ופועלת באופן הבא:

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

בדיקת תהליכים

איסוף ביקורות

בדיקת קוד המקור

קוד המקור היחיד שצריך הוא הפונקציה לחיקוי שירות לקצה העורפי שה-Agent משתמש בו ככלי.

package.json

// The function relies on the Cloud Functions framework to run.

{
  "name": "feedback-app-backend",
  "version": "0.0.1",
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  },
  ...
}

index.js

/** 
 * Handles all incoming requests.
 * 
 * It always returns OK in plain text.
 */
functions.http('feedback-app-backend', (request, response) => {
    response.send('OK');
});

service-openapi.yaml

// Defines the backend service structure and how to request it.

openapi: 3.1.0
info:
  title: Review Store
  license:
    name: Apache 2.0
    identifier: Apache-2.0
  version: 0.0.1
servers:
  - url: https://us-central1-project-0.cloudfunctions.net
paths:
  /store-review:
    post:
      operationId: storeReview
      summary: Store a new review
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                stars:
                  type: integer
                  format: int64
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: string

הפעלת מוקאפ של שירות לקצה העורפי

אתם פורסים פונקציה של Cloud Functions כדי לדמות שירות קצה עורפי שאפליקציית הסוכן של Dialogflow CX צריכה לשלב ולהפעיל ככלי.

במסוף Google Cloud, פועלים לפי השלבים הבאים:

לוחצים על תפריט ☰ > Cloud Functions.

לוחצים על יצירת פונקציה.
בקטע Basics, מגדירים את name לערך function-2.
בקטע אימות, בוחרים בלחצן האפשרויות הפעלת קריאות לא מאומתות.
בקטע Runtime, build, connections and security settings (הגדרות של זמן ריצה, build, חיבורים ואבטחה), מגדירים את Maximum number of instances (מספר המופעים המקסימלי) ל-3.
לוחצים על הבא.

מגדירים את Entry point ל-feedback-app-backend.
מחליפים את תוכן ברירת המחדל בקבצים package.json ו-index.js.
לוחצים על פריסה.

מעתיקים את כתובת ה-URL וממתינים כמה דקות עד שהפונקציה תופעל.

יצירת אפליקציית סוכן של Dialogflow CX

יצירת אפליקציה

במסוף Google Cloud, פועלים לפי השלבים הבאים:

לוחצים על תפריט ☰ > הכלי ליצירת סוכנים > אפליקציות.

לוחצים על אפליקציה חדשה.
בוחרים באפשרות סוכן.
מגדירים את השם המוצג לערך Feedback App.
לוחצים על יצירה.

הפעלת כלי

במסוף Google Cloud, פועלים לפי השלבים הבאים:

לוחצים על תפריט ☰ > הכלי ליצירת סוכנים > אפליקציות.

בוחרים את הסוכן אפליקציית משוב.
לוחצים על כלים > + יצירה.
מגדירים את Name לערך review.
בוחרים באפשרות OpenAPI.
מגדירים את הערך הבא לתיאור:

The tool takes the number of stars as a parameter of the store review method and saves it in a database for later use.

מורידים את $URL ומחליפים אותו בקובץ service-openapi.yaml בכתובת ה-URL שהעתקתם קודם.
מגדירים את YAML Schema לתוכן הערוך של הקובץ service-openapi.yaml.
לוחצים על שמירה.

Initiate agent

במסוף Google Cloud, פועלים לפי השלבים הבאים:

לוחצים על תפריט ☰ > הכלי ליצירת סוכנים > אפליקציות.

בוחרים את הסוכן אפליקציית משוב.
בוחרים באפשרות סוכנים > סוכן גנרטיבי שמוגדר כברירת מחדל.
מגדירים את שם הסוכן לערך Feedback collector.
מגדירים את goal לערך הבא:

You are an agent that collects reviews from Google Chat app developers.
A review may be between 0 and 5 stars. The more stars, the more positive the review.

מגדירים את הערך הבא להוראות:

If the developer didn't provide the number of stars, ask for the number of stars.
After the developer provides the number of stars of the review, confirm the number with the developer and use ${TOOL: review} to store the review with the number of stars.
If ${TOOL: review} fails, apologize and ask to try again later. Otherwise, thank the developer for the review.

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

אפליקציה לבדיקה

במסוף Google Cloud, פועלים לפי השלבים הבאים:

לוחצים על תפריט ☰ > הכלי ליצירת סוכנים > אפליקציות.

בוחרים את הסוכן אפליקציית משוב.
עוברים אל תצוגה מקדימה של הסוכן.
בקטע סוכן, בוחרים באפשרות איסוף משוב.
בקטע Select generative model (בחירת מודל גנרטיבי), בוחרים באפשרות gemini-pro.
כדי להתחיל, שולחים את ההודעה Hello!.

במסוף Google Cloud, פועלים לפי השלבים הבאים:

לוחצים על תפריט ☰ > Cloud Functions.

בוחרים באפשרות function-2 > Logs (פונקציה 2 > יומנים). בחלק מהיומנים, Google-Dialogflow מופיע כמתקשר.

שילוב של אפליקציית Google Chat

ב-Dialogflow CX console, פועלים לפי השלבים הבאים:

בוחרים את הפרויקט בענן ב-Google Cloud.
לוחצים על תפריט הפעולות של סוכן Feedback App.
לוחצים על העתקת השם.

במסוף Google Cloud, פועלים לפי השלבים הבאים:

עוברים להגדרות של Google Chat API.

מגדירים את שם המשאב של הסוכן או הסביבה לשם הסוכן שהעתקתם קודם.

כדי להתחיל, שולחים את ההודעה Hello! בצ'אט ישיר באפליקציית Google Chat. הסוכן מגיב באופן דומה לבדיקה שלכם במסוף Dialogflow CX.

11. הסרת המשאבים

מחיקת פרויקט בענן של Google

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

במסוף Google Cloud, פועלים לפי השלבים הבאים:

לוחצים על תפריט ☰ > IAM ואדמין > הגדרות.

לוחצים על כיבוי.
מזינים את מזהה הפרויקט.
לוחצים על Shut down anyway (כיבוי בכל זאת).

מחיקת פרויקט Apps Script

מומלץ גם למחוק את פרויקט Apps Script.

ב-Apps Script console, פועלים לפי השלבים הבאים:

בוחרים את הפרויקט הרצוי.
לוחצים על תפריט הפעולות.
לוחצים על הסרה.

12. מזל טוב

מעולה! יצרתם אפליקציות ל-Google Chat בעזרת Gemini!

מה השלב הבא?

ב-codelab הזה הצגנו רק תרחישי שימוש פשוטים, אבל יש הרבה תחומים שבהם אפשר להרחיב את השימוש באפליקציות ל-Google Chat, למשל:

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

יצירת אפליקציות ל-Google Chat עם Gemini

1. לפני שמתחילים

מהן אפליקציות ל-Google Chat עם Gemini?

למה כדאי לשלב אפליקציות של Google Chat עם Gemini?

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

מה תפתחו

אפליקציה לניהול בעיות (יצירת תוכן ושיפורו)

אפליקציית Knowledge (חיפוש נתונים)

אפליקציית משוב (שיחה)

מה תלמדו

מה צריך

2. להגדרה

הפעלת משאבים

פרויקט Apps Script

פרויקט בענן של Google Cloud

Google Chat

הורדת קוד המקור והמשאבים באופן מקומי

התקנה והגדרה של clasp

3. אפליקציה 1: בנייה

מושגים שכדאי להכיר

Vertex AI

Gemini

שירות Chat מתקדם

בדיקת הארכיטקטורה

בדיקת תהליכי עבודה

יצירת בעיה

פתרון בעיות ממרחב ייעודי

סגירת בעיה ממרחב ייעודי

בדיקת קוד המקור

עדכון פרויקט ב-Google Cloud

הפעלת ממשקי API

Initiate service account

עדכון ההגדרה של Google Chat API

עדכון פרויקט Apps Script

הגדרת קוד המקור

הגדרה של clasp הגדרות

העברת קוד המקור

אני רוצה לנסות אותו

4. אופציונלי: אפליקציה 1: הוספת דף הבית של האפליקציה

מושגים שכדאי להכיר

בדיקת תהליכי עבודה

ניהול בעיות

בדיקת קוד המקור

עדכון פרויקט ב-Google Cloud

אני רוצה לנסות

5. אופציונלי: אפליקציה 1: הוספת מעקב אחר המרחב

בדיקת מושגים

Pub/Sub

אירועים ב-Google Workspace

בדיקת תהליכי עבודה

יצירת בעיה (עדכון)

פתרון בעיה ממרחב ייעודי (עדכון)

סגירת בעיה ממרחב ייעודי (עדכון)

עיבוד מינויים

בדיקת קוד המקור

עדכון פרויקט ב-Google Cloud

הפעלת ממשקי API

הפעלת מינוי

עדכון פרויקט Apps Script

אני רוצה לנסות

6. אופציונלי: אפליקציה 1: הוספת עזרה בנושא קבלת האחר

בדיקת מושגים

בדיקת תהליכי עבודה

עיבוד מינויים (עדכון)

בדיקת קוד המקור

עדכון פרויקט Apps Script

אני רוצה לנסות

7. אופציונלי: אפליקציה 1: הוספת העדפות

בדיקת מושגים

בדיקת תהליכי עבודה

השבתת העזרה בנושא שפה מכלילה

בדיקת קוד המקור

עדכון פרויקט Apps Script

אני רוצה לנסות

השבתת העזרה

בדיקת השבתה

8. אפליקציה 2: Build

מושגים שכדאי להכיר

הארקה של AI גנרטיבי

שפה טבעית

התקנה והגדרה של `clasp`

הגדרה של `clasp` הגדרות