إنشاء تطبيقات لاستخدامها في Google Chat باستخدام Gemini

1. قبل البدء

ما هي تطبيقات Google Chat التي تتضمّن Gemini؟

تتيح تطبيقات Google Chat التي تتضمّن Gemini إجراء ما يلي:

يمكنك دمج خدماتك ومواردك في Google Chat، ما يتيح للمستخدمين الحصول على المعلومات واتّخاذ الإجراءات بدون مغادرة المحادثة.
التكامل مع نموذج الذكاء الاصطناعي التوليدي Gemini، ما يتيح إنشاء البيانات أو البحث عنها، مثل النصوص أو الصور، في أوقات محدّدة لتبسيط سير العمل

لماذا يجب دمج تطبيقات Google Chat مع Gemini؟

تندرج حالات الاستخدام النموذجية لنماذج الذكاء الاصطناعي التوليدي، مثل Gemini، ضمن الفئات التالية:

إنشاء المحتوى وتحسينه: إنشاء نصوص تسويقية أو منشورات على وسائل التواصل الاجتماعي أو صور واقعية أو تأليف موسيقى أو المساعدة في إنشاء محتوى فيديو
البحث عن البيانات استخراج إحصاءات رئيسية من قاعدة معارف غير منظَّمة، أو تلخيص النصوص الطويلة، أو تصنيف المحتوى، أو ترجمة اللغات بدقة وسرعة محسّنتَين
المحادثة المشاركة في محادثات طبيعية وغنية بالمعلومات ومبتكرة

إنّ إمكانية دمج هذه الميزات مباشرةً في واجهة Google Chat المألوفة هي فرصة كبيرة لأي شخص يريد تحسين تجربة المستخدمين وإنتاجيتهم.

المتطلبات الأساسية

معرفة أساسية بـ برمجة تطبيقات Google وGoogle Cloud وNode.js
معرفة أساسية بمفاهيم Google Chat، بما في ذلك معالجات الأحداث وأوامر الشرطة المائلة ومربّعات الحوار والبطاقات والرسائل ومصادقة التطبيقات وواجهات برمجة التطبيقات

ما يمكنك إنشاؤه

في هذا الدرس العملي، ستنشئ ثلاثة تطبيقات Google Chat باستخدام Gemini لتغطية حالات الاستخدام الثلاث التي تم تقديمها في القسم السابق.

تطبيق إدارة المشاكل (إنشاء المحتوى وتحسينه)

ينفّذ هذا التطبيق ما يلي:

إدارة المشاكل من إنشائها إلى إغلاقها من خلال التفاعلات الأساسية وصفحة التطبيق الرئيسية والمصادقة على التطبيق
يراقب الرسائل ويقدّم المساعدة في ما يتعلّق بالشمولية من خلال أحداث وأدوات ملحقات.

يمكنك استخدام Gemini لإجراء ما يلي:

إنشاء تقارير المشاكل استنادًا إلى سجلّ الرسائل وتفاصيل المشكلة
تصنيف الكلمات غير الشاملة في الرسائل التي تتضمّن طلبات مشروطة

تشمل التقنيات الرئيسية المستخدَمة Vertex AI وGemini وApps Script وواجهات برمجة التطبيقات في Google Workspace (المشرف وChat و"مستندات Google" و"أحداث Google").

تطبيق المعرفة (البحث عن البيانات)

يعتمد هذا التطبيق على Gemini لفهم الأسئلة والإجابة عنها باللغة الطبيعية وعرض مراجع المصادر من البيانات غير المنظَّمة.

تشمل التقنيات الرئيسية المستخدَمة وكيل متجر بيانات Dialogflow CX وربط 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 باستخدام "برمجة تطبيقات Google" يستند هذا الدرس التطبيقي حول الترميز إلى مشروع "برمجة تطبيقات Google" وGoogle Cloud الناتجَين.

2. طريقة الإعداد

تهيئة الموارد

في هذا القسم، يمكنك الوصول إلى الموارد التالية وضبطها من متصفّح الويب المفضّل لديك.

مشروع "برمجة تطبيقات Google"

في وحدة تحكّم برمجة تطبيقات، اتّبِع الخطوات التالية:

انقر على الإعدادات ثم فعِّل Google Apps Script API.

اختَر مشروعك.
انقر على إعدادات المشروع.
ضَع علامة في مربّع الاختيار عرض ملف البيان "appsscript.json" في المحرّر.
أعِد تسمية المشروع إلى Chat Apps Gemini.

مشروع على السحابة الإلكترونية من Google Cloud

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

اختَر مشروعك.
انقر على القائمة ☰ > واجهات برمجة التطبيقات والخدمات > شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth > تعديل التطبيق، ثم اضبط اسم التطبيق على Chat Apps Gemini.

انتقِل إلى إعدادات Google Chat API، ثم اضبط اسم التطبيق والوصف على Chat Apps Gemini.

Google Chat

في Google Chat، اتّبِع الخطوات التالية:

إذا لزم الأمر، ابدأ محادثة باستخدام تطبيق Google Chat.
أرسِل رسالة، مثل Hello، للتأكّد من أنّها تعمل.

تنزيل رمز المصدر والموارد على الجهاز

نزِّل مستودع GitHub هذا.

في بيئة التطوير المفضّلة لديك، افتح الدليل apps-script، ثم انتقِل إلى الدليل نفسه في الوحدة الطرفية.

تثبيت `clasp` وإعداده

نستخدم clasp لتعديل نُسخ رمز المصدر ونقلها بسهولة من البيئة المحلية إلى مشروع "برمجة تطبيقات Google".

في بيئتك المحلية، ثبِّت أحدث إصدارات node وnpm وclasp.

npm install -g @google/clasp

سجِّل الدخول باستخدام حسابك:

clasp login

في حال نجاح العملية، ستظهر لك شاشة تأكيد أساسية في متصفّح الويب وسيتم تعديل ملف .clasprc.json الذي يتضمّن بيانات اعتماد العميل. يمكنك العثور على مكانه في الجهاز.

3- التطبيق 1: الإنشاء

مراجعة المفاهيم

Vertex AI

توفّر منصة Vertex AI كل ما تحتاج إليه لإنشاء الذكاء الاصطناعي التوليدي واستخدامه، بما في ذلك حلول الذكاء الاصطناعي وأداة إنشاء الوكلاء وأكثر من 130 نموذجًا أساسيًا ومنصة موحّدة للذكاء الاصطناعي.

Gemini

‫Gemini هو نموذج لغوي كبير متعدد الوسائط من Google يمكن الوصول إليه من خلال Vertex AI. فهو يساعد الأشخاص على الاستفادة من إمكاناتهم إلى أقصى حد، ما يتيح لهم توسيع آفاق مخيلتهم وإثارة فضولهم وتعزيز إنتاجيتهم.

خدمة Chat المتقدّمة

تتيح لك خدمة Advanced Chat استخدام واجهة برمجة تطبيقات Google Chat في "برمجة تطبيقات Google". يتيح ذلك للبرامج النصية العثور على مساحات Chat وإنشائها وتعديلها، وإضافة أعضاء إلى المساحات أو إزالتهم منها، وقراءة الرسائل أو نشرها مع النصوص والبطاقات والمرفقات والتفاعلات.

بنية المراجعات

تم إنشاء تطبيق Google Chat هذا باستخدام "برمجة تطبيقات Google". تعمل هذه الميزة على النحو التالي:

يرسل المستخدم رسالة إلى التطبيق، إما في رسالة مباشرة أو في مساحة.
يعالج التطبيق الرسالة، وهو تطبيق تم تنفيذه في مشروع "برمجة تطبيقات Google" ومرتبط بمشروع على السحابة الإلكترونية من Google.
يتكامل التطبيق مع واجهات برمجة التطبيقات في "مستندات Google" وGoogle Chat.
يستخدم التطبيق خدمة المواقع لتخزين البيانات في مواقع النص البرمجي.
يرسل التطبيق ردًا متزامنًا، إما في رسالة مباشرة أو في المساحة الأصلية.

مراجعة خطوات المستخدم

إنشاء مشكلة

تحديد المشكلة وحلّها من المساحة المخصّصة

إغلاق المشكلة من المساحة المخصّصة

مراجعة رمز المصدر

يحتوي مشروع "برمجة تطبيقات Google" على البرامج النصية التالية:

Configuration: ثوابت يمكن تعديلها استنادًا إلى البيئة.
ChatApp: تعالج أحداث التفاعل في Google Chat، بما في ذلك الرسائل والنقرات على البطاقات وأوامر الشرطة المائلة ومربّعات الحوار.
‫Storage: دوال مساعدة تعتمد على "خدمات الخصائص".
ChatAppAuth: دوال خدمية تعتمد على مصادقة تطبيق محادثات Google.
‫Docs: دوال مساعدة تعتمد على "مستندات Google".
‫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

تفعيل واجهات برمجة التطبيقات

في وحدة تحكّم Google Cloud، فعِّل واجهات برمجة التطبيقات مستندات Google وGoogle Admin SDK وVertex AI:

انقر على القائمة ☰ > واجهات برمجة التطبيقات والخدمات > واجهات برمجة التطبيقات والخدمات المفعَّلة، ثم تأكَّد من تفعيل واجهات برمجة التطبيقات.

بدء حساب الخدمة

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انقر على القائمة ☰ > إدارة الهوية وإمكانية الوصول والمشرف > حسابات الخدمة > + إنشاء حساب خدمة.

اضبط اسم حساب الخدمة على chat-app.
اضبط وصف حساب الخدمة على Chat app auth.
انقر على إنشاء ومتابعة.
انقر على تم. ستتم إعادة توجيهك إلى صفحة حسابات الخدمة ويمكنك الاطّلاع على حساب الخدمة الذي أنشأته.

اختَر حساب الخدمة الذي تم إنشاؤه حديثًا.
انقر على علامة التبويب المفاتيح.
انقر على إضافة مفتاح.
انقر على إنشاء مفتاح جديد.
اختَر JSON.
انقر على إنشاء.

يتم إغلاق مربّع الحوار ويتم تلقائيًا تنزيل زوج المفتاح العام/الخاص الذي تم إنشاؤه حديثًا إلى بيئتك المحلية كملف JSON. يمكنك استخدام محتواه لاحقًا عند تعديل رمز المصدر لمشروعك في "برمجة التطبيقات".

تعديل إعدادات Google Chat API

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

إضافة أمر يبدأ بشرطة مائلة
اضبط الاسم على /create.
اضبط معرّف الأمر على 1.
اضبط الوصف على Create a new issue.
ضَع علامة في مربّع الاختيار يفتح مربّع حوار.
أضِف أمرًا آخر يبدأ بشرطة مائلة.
اضبط الاسم على /close.
اضبط معرّف الأمر على 2.
اضبط الوصف على Close an issue.
انقر على حفظ.

تعديل مشروع "برمجة تطبيقات Google"

غيِّر الدليل الحالي في وحدة التحكّم المحلية إلى issue-management/1-baseline. يحتوي على رمز المصدر. قبل إرسال رمز المصدر إلى مشروعك في "برمجة التطبيقات"، عليك ضبط بعض الإعدادات.

إعداد رمز المصدر

اضبط قيمة ثابتة JSON باسم CHAT_CREDENTIALS في الملف Configuration.js على محتوى ملف المفتاح الخاص الذي نزّلته سابقًا.

في Google Cloud Console، انقر على القائمة ☰ > المشرف وإدارة الهوية وإمكانية الوصول > الإعدادات.

انسخ رقم تعريف المشروع.

اضبط السلسلة الثابتة المسماة PROJECT_ID في الملف Configuration.js على رقم تعريف المشروع.

ضبط `clasp` الإعدادات

لإعداد clasp لدفع رمز المصدر إلى مشروع "برمجة تطبيقات Google" الصحيح، اتّبِع الخطوات التالية:

في وحدة تحكّم "برمجة تطبيقات Google"، اختَر مشروعك.
اختَر إعدادات المشروع (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 1.
انقر على إنشاء.

ينفّذ التطبيق ما يلي:

يُستخدَم لإغلاق مربّع الحوار.
ينشئ مساحة مخصّصة للمشكلة التي تم إنشاؤها حديثًا بالعنوان نفسه.
الانضمام إلى المساحة التي تم إنشاؤها حديثًا
يتم إرسال رسالة تحتوي على وصف للمشكلة في المساحة التي تم إنشاؤها حديثًا.
يرسل إليك رسالة مباشرة تتضمّن رابطًا إلى المساحة التي تم إنشاؤها حديثًا.

في المساحة التي تم إنشاؤها حديثًا، أرسِل رسالة تتضمّن الأمر الذي يبدأ بشرطة مائلة /close والقرار، مثل Not reproducible.

ينفّذ التطبيق ما يلي:

ينشئ مستند تقرير في "مستندات Google".
إرسال رسالة إلى المساحة المخصّصة للمشكلة مع رابط إلى مستند التقرير الذي تم إنشاؤه حديثًا

افتح مستند التقرير. ويحتوي على معلومات أساسية وسجلّ وملخّص.

4. اختياري: التطبيق 1: إضافة صفحة التطبيق الرئيسية

مراجعة المفاهيم

الصفحة الرئيسية للتطبيق هي رسالة بطاقة قابلة للتخصيص يرسلها تطبيق محادثات إلى المستخدم عندما يصل إلى علامة التبويب الصفحة الرئيسية من رسالة مباشرة مع تطبيق محادثات. ويتم استخدامها عادةً لعرض مستندات التطبيق أو نظرة عامة. من الناحية الفنية، هناك حدث مخصّص للتعامل مع هذه الرسائل، وهو يستند إلى المبادئ الأساسية نفسها التي تستند إليها رسائل البطاقات.

مراجعة خطوات المستخدم

إدارة المشاكل

مراجعة رمز المصدر

يجب تعديل مشروع "برمجة تطبيقات Google".

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 إلى التطبيق. سيفتح التطبيق مربّع حوار.
اضبط العنوان على Issue Title 2.
اضبط الوصف على المشكلة Description 2.
انقر على إنشاء.

انقر على علامة التبويب الصفحة الرئيسية من مساحتك باستخدام تطبيق Google Chat. يمكنك الاطّلاع على تفاصيل المشاكل التي أنشأتها.

5- اختياري: التطبيق 1: إضافة ميزة مراقبة المساحة

مراجعة المفاهيم

Pub/Sub

‫Pub/Sub هي خدمة مراسلة غير متزامنة وقابلة للتوسيع تفصل الخدمات التي تنتج الرسائل عن الخدمات التي تعالجها. تتيح لك خدمة Pub/Sub إنشاء أنظمة تضم منتجي ومستهلكي الأحداث، يُسمى ذلك بالناشرين ومشتركين. يتواصل الناشرون مع المشتركين بشكل غير متزامن عن طريق بث الأحداث، بدلاً من إجراء مكالمات الإجراءات عن بُعد المتزامنة (RPC).

يرسل الناشرون الأحداث إلى خدمة Pub/Sub بدون الاهتمام بكيفية معالجة هذه الأحداث أو وقت معالجتها. وبعد ذلك، توفّر خدمة Pub/Sub الأحداث إلى جميع الخدمات التي تتفاعل معها. في الأنظمة التي تتواصل من خلال استدعاء الإجراءات عن بُعد، يجب أن ينتظر الناشرون المشتركين لتلقّي البيانات. ومع ذلك، فإنّ الدمج غير المتزامن في Pub/Sub يزيد من مرونة النظام العام وقوته.

الموضوع: مورد مسمّى يمثّل خلاصة للرسائل. يجب إنشاء موضوع قبل أن تتمكّن من نشره أو الاشتراك فيه.

الاشتراك: لتلقّي الرسائل المنشورة في موضوع معيّن، يجب إنشاء اشتراك في هذا الموضوع. يتلقّى تطبيق المشترك الرسائل المنشورة في الموضوع ويعالجها. يمكن أن يتضمّن الموضوع اشتراكات متعددة، ولكن ينتمي الاشتراك المحدّد إلى موضوع واحد.

أحداث Google Workspace

تمثّل أحداث Google Workspace التغييرات التي تطرأ على مراجع Google Workspace، مثل إنشاء المراجع أو تعديلها أو حذفها. يمكن للتطبيقات الاشتراك في مراجع Google Workspace لتلقّي الأحداث ذات الصلة ومعالجتها بشكل غير متزامن.

في ما يلي كيفية إرسال "واجهة برمجة تطبيقات أحداث Google Workspace" للأحداث إلى تطبيق من خلال اشتراك:

يشترك التطبيق في مورد في أحد تطبيقات Google Workspace، مثل مساحة.
تتغيّر الموارد التي اشترك فيها التطبيق.
يرسل تطبيق Google Workspace حدثًا إلى موضوع في Pub/Sub، والذي يعمل كنقطة نهاية للإشعارات الخاصة باشتراك Google Workspace للتطبيق. يحتوي الحدث على بيانات حول التغييرات التي تم إجراؤها على المورد.
يعالج التطبيق رسالة Pub/Sub التي تحتوي على الحدث، ويتخذ الإجراء اللازم إذا لزم الأمر.

مراجعة خطوات المستخدم

إنشاء مشكلة (تعديل)

تحديد المشكلة وحلّها من المساحة المخصّصة (تعديل)

إغلاق المشكلة من المساحة المخصّصة (تعديل)

معالجة الاشتراكات

مراجعة رمز المصدر

يجب تعديل مشروع "برمجة تطبيقات Google".

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

تفعيل واجهات برمجة التطبيقات

في Google Cloud Console، فعِّل "أحداث Google Workspace" وPubSub.

انقر على القائمة ☰ > واجهات برمجة التطبيقات والخدمات > واجهات برمجة التطبيقات والخدمات المفعَّلة، ثم تأكَّد من تفعيل كليهما.

بدء الاشتراك

عليك إنشاء موضوع Pub/Sub والاشتراك فيه ليتم نشر جميع أحداث مساحة العمل.

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انتقِل إلى القائمة ☰ > Pub/Sub > المواضيع.

انقر على إنشاء موضوع.
اضبط رقم تعريف الموضوع على workspace-events.
ضَع علامة في مربّع الاختيار إضافة اشتراك تلقائي.
انقر على إنشاء.

لمنح الإذن بنشر رسائل Pub/Sub إلى الموضوع الذي أنشأته حديثًا من Google Chat، اتّبِع الخطوات التالية:

اختَر الموضوع من القائمة.
انقر على علامة التبويب الأذونات.
أضِف chat-api-push@system.gserviceaccount.com إلى الجهات الرئيسية الجديدة.
اختَر ناشر Pub/Sub في الدور.
انقر على حفظ.

تعديل مشروع "برمجة تطبيقات Google"

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انتقِل إلى القائمة ☰ > إدارة الهوية وإمكانية الوصول (IAM) & المشرف > الإعدادات.

انسخ رقم تعريف المشروع.

في بيئتك المحلية، اتّبِع الخطوات التالية:

غيِّر الدليل الحالي في نافذة الأوامر إلى 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 إلى التطبيق. سيفتح التطبيق مربّع حوار.
اضبط العنوان على Issue Title 3.
اضبط الوصف على المشكلة Description 3.
انقر على إنشاء.
في المساحة التي تم إنشاؤها حديثًا، أرسِل بضع رسائل تناقش المشكلة.
أرسِل رسالة باستخدام أمر يبدأ بشرطة مائلة /close والدقة المطلوبة، مثل Fixed.

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انتقِل إلى القائمة ☰ > Pub/Sub > الاشتراكات.

اختَر اشتراك workspace-events-sub.
انقر على علامة التبويب الرسائل.
انقر على سحب. يعرض الجدول الرسائل ذات الصلة بالمحتوى الذي أرسلته إلى المساحة التي تم إنشاؤها حديثًا.

في وحدة تحكّم برمجة تطبيقات، اتّبِع الخطوات التالية:

اختَر مشروعك.
انقر على أداة التعديل.
اختَر ملف WorkspaceEvent.gs.
انقر على processSubscription في قسم التشغيل.
انقر على Run.يمكنك الاطّلاع من سجلّ التنفيذ على أنّه تمت معالجة الرسائل.

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انتقِل إلى القائمة ☰ > Pub/Sub > الاشتراكات.

اختَر اشتراك workspace-events-sub.
انقر على علامة التبويب الرسائل.
انقر على سحب. لم يعُد الجدول يعرض الرسائل ذات الصلة بما أرسلته إلى المساحة التي تم إنشاؤها حديثًا.

في Google Chat، في المساحة المخصّصة للمشكلة الثالثة التي أنشأتها باستخدام أمر يبدأ بشرطة مائلة /create، أرسِل بضع رسائل أخرى تناقش المشكلة.

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انتقِل إلى القائمة ☰ > Pub/Sub > الاشتراكات.

اختَر اشتراك workspace-events-sub.
انقر على علامة التبويب الرسائل.
انقر على سحب. لا يعرض الجدول الرسائل ذات الصلة بما أرسلته إلى المساحة التي تم إنشاؤها حديثًا.

6. اختياري: التطبيق 1: إضافة مساعدة بشأن الشمولية

مراجعة المفاهيم

تلقين الذكاء الاصطناعي التوليدي هو فنّ تصميم التعليمات أو الأسئلة لتوجيه نموذج الذكاء الاصطناعي التوليدي نحو نوع محدّد من النتائج المطلوبة. من الممارسات الشائعة حصر الإجابات من خلال إضافة قواعد وشروط في الطلبات. يمكن أن يساعد ذلك في جعل الناتج آمنًا وملائمًا ومتسقًا ومتوافقًا مع التوقعات.

مراجعة خطوات المستخدم

معالجة الاشتراكات (تعديل)

مراجعة رمز المصدر

يجب تعديل مشروع "برمجة تطبيقات Google".

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;
}

تعديل مشروع "برمجة تطبيقات Google"

في بيئتك المحلية، اتّبِع الخطوات التالية:

غيِّر الدليل الحالي في نافذة الأوامر إلى issue-management/4-inclusivity-help. يحتوي على رمز المصدر الذي تحتاجه.
انسخ ملف issue-management/3-message-monitoring/.clasp.json إلى الدليل الحالي.
انسخ ملف issue-management/3-message-monitoring/Configuration.js إلى الدليل الحالي ليحلّ محل الملف الحالي.
نفِّذ الأمر التالي:

clasp push

جرِّبه

في Google Chat، اتّبِع الخطوات التالية:

أرسِل رسالة مباشرة تتضمّن الأمر الذي يبدأ بشرطة مائلة /create إلى التطبيق. سيفتح التطبيق مربّع حوار.
اضبط العنوان على Issue Title 4.
اضبط الوصف على المشكلة Description 4.
انقر على إنشاء.
في المساحة التي تم إنشاؤها حديثًا، أرسِل It happened to me last week as well.

في وحدة تحكّم برمجة تطبيقات، اتّبِع الخطوات التالية:

اختَر مشروعك.
انقر على أداة التعديل.
اختَر ملف WorkspaceEvent.gs.
انقر على processSubscription في قسم التشغيل.
انقر على تشغيل. يمكنك الاطّلاع من سجلّ التنفيذ على أنّه تمت معالجة الرسائل.

في Google Chat، اتّبِع الخطوات التالية:

لاحظ أنّ التطبيق لم يرسل أي مساعدة بشأن الشمولية في المساحة التي تم إنشاؤها حديثًا.
في المساحة التي تم إنشاؤها حديثًا، أرسِل الرسالة I had to add myself from the master to fix it.

في وحدة تحكّم برمجة تطبيقات، اتّبِع الخطوات التالية:

اختَر مشروعك.
انقر على أداة التعديل.
اختَر ملف WorkspaceEvent.gs.
انقر على processSubscription في قسم التشغيل.
انقر على تشغيل. يمكنك الاطّلاع من سجلّ التنفيذ على أنّه تمت معالجة الرسائل. في Google Chat، أرسل التطبيق رسالة مساعدة بشأن التضمين في المساحة التي تم إنشاؤها حديثًا.

7. اختياري: التطبيق 1: إضافة الإعدادات المفضّلة

مراجعة المفاهيم

التطبيق المصغّر الخاص بالملحقات هو تطبيق مصغّر بدون حدود مُرفق بأسفل الرسالة التي يرسلها التطبيق. ويُستخدم عادةً للسماح للمستخدم بالتفاعل بسرعة مع الرسائل في سياقها المحدّد. من الناحية الفنية، تستند إلى المبادئ الأساسية نفسها التي تستند إليها أزرار البطاقات.

مراجعة خطوات المستخدم

إيقاف ميزة "المساعدة في تعزيز الشمولية"

مراجعة رمز المصدر

يجب تعديل مشروع "برمجة تطبيقات Google".

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
              }]
            }}
          }]}}]
        }, ...);
        ...
      }
      ...
    }
    ...
  }
  ...
}

تعديل مشروع "برمجة تطبيقات Google"

في بيئتك المحلية، اتّبِع الخطوات التالية:

غيِّر الدليل الحالي في نافذة الأوامر إلى 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.

في وحدة تحكّم برمجة تطبيقات، اتّبِع الخطوات التالية:

اختَر مشروعك.
انقر على أداة التعديل.
اختَر ملف WorkspaceEvent.gs.
انقر على processSubscription في قسم التشغيل.
انقر على تشغيل. يمكنك الاطّلاع من سجلّ التنفيذ على أنّه تمت معالجة الرسائل.

في Google Chat، اتّبِع الخطوات التالية:

لاحظ أنّ التطبيق أرسل رسالة تتضمّن مساعدة بشأن التضمين إلى المساحة المخصّصة للمشكلة في تطبيق مصغّر خاص بالملحقات.
انقر على أداة الملحق لإيقاف ميزة "المساعدة في التضمين".

إيقاف الشيك

في Google Chat، في المساحة المخصّصة للمشكلة الرابعة التي أنشأتها باستخدام أمر يبدأ بشرطة مائلة /create، أرسِل الرسالة I had to add myself from the master to fix.

في وحدة تحكّم برمجة تطبيقات، اتّبِع الخطوات التالية:

اختَر مشروعك.
انقر على أداة التعديل.
اختَر ملف WorkspaceEvent.gs.
انقر على processSubscription في قسم التشغيل.
انقر على تشغيل. يمكنك الاطّلاع من سجلّ التنفيذ على أنّه تمت معالجة الرسائل. في Google Chat، لم يرسل التطبيق رسالة تتضمّن مساعدة بشأن الشمولية إلى المساحة المخصّصة للمشكلة لأنّها كانت غير مفعّلة.

8. التطبيق 2: الإنشاء

مراجعة المفاهيم

تحديد مصدر الذكاء الاصطناعي التوليدي

تهدف هذه العملية إلى جعل نماذج الذكاء الاصطناعي أكثر دقة وموثوقية من خلال ربطها بمصادر معرفة يمكن التحقّق منها. تساعد هذه التقنية في منع الذكاء الاصطناعي من اختراع المعلومات ويمكن أن تساعد في جعل الردود ذات صلة بالسياق وأقل تحيزًا.

اللغة الطبيعية

أي لغة يتحدث بها البشر أو يكتبونها للتواصل اليومي، على عكس اللغات الاصطناعية أو المستندة إلى الكمبيوتر

Cloud Storage

تتيح خدمة Cloud Storage تخزين أي كمية من البيانات في جميع أنحاء العالم واستردادها في أي وقت. يمكن استخدامها في مجموعة من السيناريوهات، بما في ذلك تقديم محتوى المواقع الإلكترونية، أو تخزين البيانات لأغراض الأرشفة واسترداد البيانات في حالات الكوارث، أو توزيع عناصر البيانات الكبيرة على المستخدمين من خلال التنزيل المباشر.

مخزن بيانات 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 Console، اتّبِع الخطوات التالية:

فعِّل واجهتَي برمجة التطبيقات Dialogflow API وCloud Storage API.

فعِّل واجهة برمجة التطبيقات Vertex AI Agent Builder API.

انقر على القائمة ☰ > واجهات برمجة التطبيقات والخدمات > واجهات برمجة التطبيقات والخدمات المفعَّلة، ثم تأكَّد من تفعيل جميع واجهات برمجة التطبيقات.

إنشاء وكيل مستودع بيانات في Dialogflow CX

بدء بيانات المعرفة

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انقر على القائمة ☰ > Cloud Storage > الحِزم.

انقر على إنشاء.
اضبط قيمة الاسم على gchat-knowledge.
انقر على إنشاء.

اختَر حزمة gchat-knowledge.
انقر على تحميل ملفات.
نزِّل الملف google-chat-overview.pdf واختَره من بيئة التشغيل المحلية.

إنشاء تطبيق

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انقر على القائمة ☰ > أداة إنشاء الوكيل > التطبيقات.

انقر على تطبيق جديد.
اختَر نوع محادثة Chat.

اضبط Company name على اسم شركتك.
ضبط السمة Agent name على knowledge
انقر على متابعة.

انقر على إنشاء مستودع بيانات جديد.
اختَر "التخزين في السحابة الإلكترونية" كمصدر البيانات.

انقر على ملف.
انقروا على تصفّح.
اختَر ملف google-chat-overview.pdf.
انقر على متابعة.
اضبط اسم مستودع البيانات على gchat-knowledge-ds.
انقر على إنشاء.

اختَر مخزن البيانات gchat-knowledge-ds في الجدول.
انقر على إنشاء.

بعد بضع دقائق، انقر على القائمة ☰ > أداة إنشاء الوكيل > التطبيقات ولاحظ أنّه يمكنك رؤية التطبيق.

انقر على القائمة ☰ > أداة إنشاء العملاء الافتراضيين > مخازن البيانات.

انقر على مستودع البيانات gchat-knowledge-ds. عدد المستندات هو 1، ما يشير إلى أنّها جاهزة.

إكمال التطبيق واختباره

في وحدة تحكّم Dialogflow CX، اتّبِع الخطوات التالية:

اختَر مشروعك على Google Cloud.
اختَر وكيل قاعدة المعرفة.

انقر على إعدادات الوكيل > الذكاء الاصطناعي التوليدي > الوكيل التوليدي.
بدِّل النموذج من Text Bison إلى Gemini Pro.
انقر على حفظ.

انقر على اختبار الوكيل.
أرسِل What is Google Chat?. يردّ الوكيل بشيء ذي صلة.

دمج تطبيق محادثات Google Chat

في وحدة تحكّم Dialogflow CX، اتّبِع الخطوات التالية:

اختَر مشروعك على Google Cloud.
في صفّ وكيل المعلومات، انقر على > نسخ الاسم.

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انتقِل إلى إعدادات Google Chat API.

ضمن إعدادات الاتصال، اختَر Dialogflow.
ضمن إعدادات Dialogflow، اختَر Dialogflow CX.
اضبط اسم مورد الوكيل أو البيئة على اسم الوكيل الذي نسخته.
أزِل الأمرَين اللذين يبدآن بشرطة مائلة.

في Google Chat، أرسِل What is Google Chat? في رسالة مباشرة إلى تطبيق Google Chat. سيردّ الوكيل برسالة مفيدة.

9- اختياري: التطبيق 2: إضافة مصادر

مراجعة المفاهيم

الويب هوك في Dialogflow CX

خدمة تستضيف منطق النشاط التجاري أو تستدعي خدمات أخرى أثناء جلسة Dialogflow CX، يمكن أن تعتمد خطافات الويب على البيانات التي تم استخراجها من خلال معالجة اللغة الطبيعية لإنشاء ردود ديناميكية أو التحقّق من صحة البيانات التي تم جمعها أو تشغيل إجراءات في الخلفية.

Cloud Functions

تُعدّ Cloud Functions رائعة لإنشاء أنظمة خلفية بدون خادم، ومعالجة البيانات في الوقت الفعلي، وإنشاء تطبيقات ذكية. لا توجد خوادم يجب توفيرها أو إدارتها أو تصحيحها أو تعديلها. وهي تتكيّف تلقائيًا حسب الحاجة، وتتوفّر بشكل كبير، وتتجاوز الأخطاء.

مراجعة مسارات المستخدمين

الإجابة عن السؤال (تعديل)

مراجعة رمز المصدر

رمز المصدر الوحيد الذي تحتاج إليه هو الدالة التي تعمل على تكييف ردود الوكيل مع رسائل Google Chat. يتم استخدامه كخطاف ويب.

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 Console، اتّبِع الخطوات التالية:

فعِّل واجهات برمجة التطبيقات Cloud Build وCloud Functions وCloud Logging وArtifact Registry وCloud Run.

انقر على القائمة ☰ > واجهات برمجة التطبيقات والخدمات > واجهات برمجة التطبيقات والخدمات المفعَّلة، ثم تأكَّد من تفعيل واجهات برمجة التطبيقات.

تعديل وكيل مستودع البيانات في Dialogflow CX

عليك نشر Cloud Function وتعديل خطاف الويب في Dialogflow CX لتشغيله باستخدام مصادر متعددة عند الإمكان.

عرض مصادر متعددة

بشكلٍ تلقائي، لا يعرض وكيل متجر البيانات الجديد سوى مصدر واحد كحدّ أقصى، ولكن يمكنك تغيير ذلك لعرض المزيد.

في وحدة تحكّم Dialogflow CX، اتّبِع الخطوات التالية:

اختَر مشروعك على Google Cloud.
اختَر وكيل قاعدة المعرفة.
انقر على صفحة البدء.
انقر على تعديل مستودعات البيانات.
ضمن قسم ردود الوكيل، اضبط خيارات الردود من مخزن البيانات على 5.
انقر على حفظ.

بدء Cloud Function

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انقر على القائمة ☰ > Cloud Functions.

انقر على إنشاء دالة.
ضمن الأساسيات، اضبط الاسم على function-1.
ضمن المصادقة، انقر على زر الاختيار "السماح بعمليات الاستدعاء غير المصادَق عليها".
ضمن إعدادات وقت التشغيل والإنشاء والاتصالات والأمان، اضبط الحد الأقصى لعدد الآلات الافتراضية على 3.
انقر على التالي.

اضبط نقطة الدخول على agent-response-adapter.
استبدِل المحتوى التلقائي بالملفَين package.json وindex.js.
انقر على نشر.

انسخ عنوان URL أثناء انتظارك لبضع دقائق حتى يتم تفعيل الدالة.

بدء عملية الويب هوك

عليك ضبط وكيل Dialogflow CX لاستخدام خطاف ويب يؤدي إلى تشغيل الدالة التي تم نشرها حديثًا.

في وحدة تحكّم Dialogflow CX، اتّبِع الخطوات التالية:

اختَر مشروعك على Google Cloud.
اختَر وكيل قاعدة المعرفة.
انقر على إدارة > خطافات الويب > إنشاء.
اضبط الاسم المعروض على Google Chat Response Adapter.
اضبط رابط ويب هوك على عنوان URL الذي نسخته سابقًا.
انقر على حفظ.

انقر على إنشاء.
انقر على صفحة البدء.
انقر على تعديل مستودعات البيانات.
ضمن إعدادات الويب هوك، انقر على زر التبديل تفعيل الويب هوك.
اختَر محوّل استجابة Google Chat لخدمة الويب هوك.
اضبط tag على arbitrary_tag.
انقر على حفظ.

تطبيق الاختبار

في Google Chat، أرسِل What is Google Chat? في رسالة مباشرة إلى تطبيق محادثات Google Chat. سيردّ عليك الوكيل برسالة مفيدة وبطاقة تتضمّن المصادر، إن وُجدت.

10. التطبيق 3: الإنشاء

مراجعة المفاهيم

التفاعلات الحوارية

وهي عبارة عن تبادل المعلومات أو الأفكار بين شخصين أو أكثر من خلال اللغة الطبيعية. ويختلف ذلك عن الواجهات الفنية التي تعتمد غالبًا على عمليات تبادل غير مرتبطة بحالة، ومنظَّمة للغاية، وغير متسامحة.

مواصفات OpenAPI

وهي توفّر وسيلة متّسقة لنقل المعلومات خلال كل مرحلة من مراحل دورة حياة واجهة برمجة التطبيقات. وهي لغة مواصفات لواجهات برمجة التطبيقات المستندة إلى HTTP تحدّد البنية والصيغة بطريقة لا ترتبط بلغة البرمجة التي تم إنشاء واجهة برمجة التطبيقات بها. تتم كتابة مواصفات واجهة برمجة التطبيقات عادةً بلغة YAML أو JSON، ما يتيح سهولة مشاركة المواصفات واستخدامها.

وكيل Dialogflow CX

الوحدة الأساسية لتطبيقات الوكلاء يحتوي تطبيق الوكيل عادةً على العديد من الوكلاء، حيث يتم تحديد كل وكيل للتعامل مع مهام معيّنة. يتم تزويد النموذج اللغوي الكبير ببيانات الوكيل، ما يتيح له الحصول على المعلومات التي يحتاجها للإجابة عن الأسئلة وتنفيذ المهام. يمكن لكل وكيل تقديم معلومات أو إرسال طلبات بحث إلى خدمات خارجية أو تأجيل معالجة المحادثة إلى مسار Dialogflow CX أو وكيل آخر لمعالجة المهام الفرعية.

أداة Dialogflow CX

تُستخدَم الأدوات لربط تطبيقات الوكيل بالأنظمة الخارجية. يمكن لهذه الأنظمة تعزيز معرفة تطبيقات الوكلاء وتمكينها من تنفيذ المهام المعقّدة بكفاءة.

بنية المراجعات

تم إنشاء تطبيق محادثات Google Chat هذا باستخدام Dialogflow CX ويعمل على النحو التالي:

يرسل المستخدم رسالة إلى التطبيق، إما في رسالة مباشرة أو في مساحة.
يعالج التطبيق، وهو وكيل Dialogflow CX ومرتبط بمشروع على السحابة الإلكترونية من Google، الرسالة.
يتكامل التطبيق مع وكيل.
يرسل التطبيق ردًا متزامنًا، إما في رسالة مباشرة أو في المساحة الأصلية.

مراجعة مسارات المستخدمين

جمع المراجعات

مراجعة رمز المصدر

رمز المصدر الوحيد الذي تحتاج إليه هو الدالة لمحاكاة خدمة الخلفية التي يستخدمها الوكيل كأداة.

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.

انقر على إنشاء دالة.
ضمن الأساسيات، اضبط الاسم على function-2.
ضمن المصادقة، انقر على زر الاختيار السماح بعمليات الاستدعاء غير المصادَق عليها.
ضمن إعدادات وقت التشغيل والإنشاء والاتصالات والأمان، اضبط الحد الأقصى لعدد الآلات الافتراضية على 3.
انقر على التالي.

اضبط نقطة الدخول على feedback-app-backend.
استبدِل المحتوى التلقائي بالملفَين package.json وindex.js.
انقر على نشر.

انسخ عنوان URL أثناء انتظارك لبضع دقائق حتى يتم تفعيل الدالة.

إنشاء تطبيق وكيل Dialogflow CX

إنشاء تطبيق

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انقر على القائمة ☰ > أداة إنشاء الوكيل > التطبيقات.

انقر على تطبيق جديد.
انقر على الوكيل.
اضبط الاسم المعروض على Feedback App.
انقر على إنشاء.

بدء الأداة

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انقر على القائمة ☰ > أداة إنشاء الوكيل > التطبيقات.

اختَر وكيل تطبيق الملاحظات.
انقر على الأدوات > + إنشاء.
اضبط الاسم على 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.
انقر على حفظ.

بدء الوكيل

في وحدة تحكّم 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، اتّبِع الخطوات التالية:

انقر على القائمة ☰ > أداة إنشاء الوكيل > التطبيقات.

اختَر وكيل تطبيق الملاحظات.
انتقِل إلى معاينة الوكيل.
ضمن الوكيل، اختَر أداة جمع الملاحظات.
ضمن اختيار نموذج إنشاء، اختَر gemini-pro.
أرسِل الرسالة Hello! للبدء.

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انقر على القائمة ☰ > Cloud Functions.

اختَر function-2 > السجلات. تعرض بعض السجلات Google-Dialogflow كمتّصل.

دمج تطبيق محادثات Google Chat

في وحدة تحكّم Dialogflow CX، اتّبِع الخطوات التالية:

اختَر مشروعك على Google Cloud.
انقر على قائمة الإجراءات الخاصة بعميل Feedback App.
انقر على نسخ الاسم.

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انتقِل إلى إعدادات Google Chat API.

اضبط اسم مورد الوكيل أو البيئة على اسم الوكيل الذي نسخته سابقًا.

في Google Chat، أرسِل Hello! في رسالة مباشرة إلى تطبيق محادثات Google Chat للبدء. يستجيب الوكيل بشكل مشابه لاختبارك من وحدة تحكّم Dialogflow CX.

11. تَنظيم

حذف مشروع على السحابة الإلكترونية من Google Cloud

لتجنُّب تحمّل رسوم على حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا الدرس العملي، ننصحك بحذف مشروع على السحابة الإلكترونية.

في وحدة تحكّم Google Cloud، اتّبِع الخطوات التالية:

انقر على القائمة ☰ > إدارة الهوية وإمكانية الوصول والمشرف > الإعدادات.

انقر على إيقاف.
أدخِل رقم تعريف المشروع.
انقر على إيقاف الاستضافة على البنية الأساسية القديمة.

حذف مشروع "برمجة تطبيقات Google"

ننصحك أيضًا بحذف مشروع "برمجة تطبيقات Google".

في وحدة تحكّم برمجة تطبيقات، اتّبِع الخطوات التالية:

اختَر مشروعك.
انقر على قائمة الإجراءات.
انقر على إزالة.

12. تهانينا

تهانينا! لقد أنشأت تطبيقات Google Chat باستخدام Gemini.

ما هي الخطوات التالية؟

لقد عرضنا في هذا الدرس التطبيقي حول الترميز حالات استخدام بسيطة فقط، ولكن هناك العديد من مجالات التوسّع التي قد تحتاج إلى أخذها في الاعتبار في تطبيقات Google Chat، مثل ما يلي:

التكامل مع نماذج الذكاء الاصطناعي التوليدي الأخرى، بما في ذلك النماذج المخصّصة
أن تتوافق مع أنواع أخرى من الوسائط، مثل الصوت والصور والفيديوهات
استخدام تعدُّد الوسائط.
الاعتماد على قدرات استيعاب أكبر وحلقات الملاحظات
نشر تطبيقات Google Chat جاهزة للاستخدام في السوق تتوفّر الكثير من المراجع للمطوّرين، مثل فيديوهات YouTube ومواقع المستندات وعيّنات التعليمات البرمجية والأدلة التعليمية.
فعِّل Google Chat لمؤسستك. تسهّل عليك ميزة "وضع الاستيراد" البدء.

إنشاء تطبيقات لاستخدامها في Google Chat باستخدام Gemini

1. قبل البدء

ما هي تطبيقات Google Chat التي تتضمّن Gemini؟

لماذا يجب دمج تطبيقات Google Chat مع Gemini؟

المتطلبات الأساسية

ما يمكنك إنشاؤه

تطبيق إدارة المشاكل (إنشاء المحتوى وتحسينه)

تطبيق المعرفة (البحث عن البيانات)

تطبيق الملاحظات (محادثة)

ما ستتعرّف عليه

المتطلبات

2. طريقة الإعداد

تهيئة الموارد

مشروع "برمجة تطبيقات Google"

مشروع على السحابة الإلكترونية من Google Cloud

Google Chat

تنزيل رمز المصدر والموارد على الجهاز

تثبيت clasp وإعداده

3- التطبيق 1: الإنشاء

مراجعة المفاهيم

Vertex AI

Gemini

خدمة Chat المتقدّمة

بنية المراجعات

مراجعة خطوات المستخدم

إنشاء مشكلة

تحديد المشكلة وحلّها من المساحة المخصّصة

إغلاق المشكلة من المساحة المخصّصة

مراجعة رمز المصدر

تعديل مشروع على السحابة الإلكترونية من Google Cloud

تفعيل واجهات برمجة التطبيقات

بدء حساب الخدمة

تعديل إعدادات Google Chat API

تعديل مشروع "برمجة تطبيقات Google"

إعداد رمز المصدر

ضبط clasp الإعدادات

إرسال رمز المصدر

جرِّب هذه الميزة

4. اختياري: التطبيق 1: إضافة صفحة التطبيق الرئيسية

مراجعة المفاهيم

مراجعة خطوات المستخدم

إدارة المشاكل

مراجعة رمز المصدر

تعديل مشروع على السحابة الإلكترونية من Google Cloud

جرِّبه

5- اختياري: التطبيق 1: إضافة ميزة مراقبة المساحة

مراجعة المفاهيم

Pub/Sub

أحداث Google Workspace

مراجعة خطوات المستخدم

إنشاء مشكلة (تعديل)

تحديد المشكلة وحلّها من المساحة المخصّصة (تعديل)

إغلاق المشكلة من المساحة المخصّصة (تعديل)

معالجة الاشتراكات

مراجعة رمز المصدر

تعديل مشروع على السحابة الإلكترونية من Google Cloud

تفعيل واجهات برمجة التطبيقات

بدء الاشتراك

تعديل مشروع "برمجة تطبيقات Google"

جرِّبه

6. اختياري: التطبيق 1: إضافة مساعدة بشأن الشمولية

مراجعة المفاهيم

مراجعة خطوات المستخدم

معالجة الاشتراكات (تعديل)

مراجعة رمز المصدر

تعديل مشروع "برمجة تطبيقات Google"

جرِّبه

7. اختياري: التطبيق 1: إضافة الإعدادات المفضّلة

مراجعة المفاهيم

مراجعة خطوات المستخدم

إيقاف ميزة "المساعدة في تعزيز الشمولية"

مراجعة رمز المصدر

تعديل مشروع "برمجة تطبيقات Google"

جرِّبه

إيقاف المساعدة

إيقاف الشيك

8. التطبيق 2: الإنشاء

مراجعة المفاهيم

تحديد مصدر الذكاء الاصطناعي التوليدي

اللغة الطبيعية

تثبيت `clasp` وإعداده

ضبط `clasp` الإعدادات