ضبط Google Chat API

يتطلّب كل تطبيق Google Chat تنشئه مشروعًا خاصًا به على Google Cloud مع تفعيل واجهة برمجة التطبيقات Chat API وضبطها.

لإجراء طلبات بيانات من واجهة برمجة التطبيقات للقراءة فقط باستخدام مصادقة المستخدم، مثل الحصول على المساحات وإدراج الرسائل، ما عليك سوى تفعيل واجهة برمجة التطبيقات و إنشاء عميل OAuth.

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

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

• حساب Business أو Enterprise على Google Workspace مع إمكانية الوصول إلى Google Chat
• أنشئ مشروعًا على Google Cloud.
• اضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth.
• تفعيل Google Chat API

اختيار اسم معروض وصورة رمزية ووصف لتطبيق Chat

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

قبل إعداد تطبيق Chat، عليك تجهيز المعلومات التالية:

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

على سبيل المثال، إذا طلبت الطريقة spaces.create()، يتضمّن Chat اسم التطبيق في Chat في وصف من أنشأ المساحة، كما هو موضّح في الصورة التالية:

للتفاعل مع تطبيقات Chat، يطّلع المستخدمون أيضًا على هذه المعلومات أو يستخدمونها بالطرق التالية:

• يمكنك الإشارة إلى تطبيق Chat باستخدام @ لإضافته إلى مساحة أو إرسال رسالة إليه.
• ابحث عن رسالة مباشرة مع تطبيق Chat وابدأها. في قائمة التطبيقات، تعرض الرسائل المباشرة اسم تطبيق Chat وصورته الرمزية.
• من خانة إدخال المحتوى، يمكن للمستخدمين تصفُّح تطبيقات Chat والاطّلاع على اسمها وصورة الأفاتار ووصفها.

ضبط إعدادات تطبيق Chat في Google Cloud Console

عندما تتوفّر لديك تفاصيل تطبيق Chat، افتح مشروعك على السحابة الإلكترونية واضبط Chat API:

1. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة Chat API وانقر على صفحة الإعدادات:

   الانتقال إلى صفحة "إعدادات Chat API"

2. ضمن معلومات التطبيق، املأ حقول اسم التطبيق وعنوان URL للأفاتار والوصف.

3. اختياري: املأ حقل الوصف الطويل (متاح كجزء من برنامج المطوّرين الحصري في Google Workspace).

4. اختياري: من قائمة بناء جملة الترميز، اختَر بناء جملة الترميز التلقائي (Markdown أو Chat) لرسائل تطبيق Chat. لمزيد من المعلومات حول تنسيق النص وكيفية تحديد Chat لبنية الترميز لطلبات البيانات من واجهة برمجة التطبيقات، يُرجى الاطّلاع على تنسيق الرسائل.

5. ضمن الميزات التفاعلية، يمكنك ضبط ما إذا كان تطبيق Chat يستجيب لتفاعلات المستخدمين:

   لإنشاء تطبيق Chat تفاعلي، فعِّل تفعيل الميزات التفاعلية وأكمِل ما يلي:

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

   2. ضمن إعدادات الاتصال، اختَر البنية التي تريد استخدامها لتلقّي كائنات الأحداث من Chat:

      • لاستخدام خدمة HTTP، اختَر عنوان URL لنقطة نهاية HTTP وأدخِل عنوان URL.
      • لاستخدام مشروع "برمجة تطبيقات Google"، اختَر برمجة التطبيقات وقدِّم رقم تعريف النشر للمشروع.
      • لاستخدام وكيل Dialogflow، اختَر Dialogflow، ثم اختَر Dialogflow CX أو Dialogflow ES، وقدِّم اسم المرجع الخاص بالوكيل.
      • لاستخدام Pub/Sub، اختَر Cloud Pub/Sub وأدخِل اسم الموضوع.

   3. اختياري: لتوجيه كائنات الأحداث إلى نقاط نهاية أو دوال محدّدة، انتقِل إلى إعدادات الاتصال > المشغّلات وقدِّم أو عدِّل نقاط نهاية عمليات الاستدعاء أو الدوال لمشغّلات Chat التالية:

      • الصفحة الرئيسية للتطبيق (في حال تفعيل إتاحة الصفحة الرئيسية للتطبيق): يفتح المستخدم علامة التبويب الصفحة الرئيسية في رسالة مباشرة على الخاص مع تطبيق Chat.
      • تمت الإضافة إلى المساحة: يضيف المستخدم تطبيق Chat إلى محادثة جماعية أو مساحة، أو يثبّت تطبيق Chat للرسائل بين شخصَين.
      • رسالة: يرسل المستخدم رسالة إلى تطبيق Chat، مثلاً رسالة مباشرة أو إشارة باستخدام @إلى تطبيق Chat في مساحة تضم عدة مستخدمين.
      • تمت الإزالة من المساحة: يشير هذا الحدث إلى أنّ أحد المستخدمين ألغى تثبيت تطبيق Chat أو أزاله من مساحة.
      • أمر التطبيق: يستدعي المستخدم أمرًا سريعًا أو أمرًا يبدأ بشرطة مائلة أو إجراء رسالة من تطبيق Chat.

   4. اختياري: يمكنك إضافة ميزات تفاعلية أخرى، مثل الجلسات أو الطلبات الأولية أو الأوامر (الأوامر السريعة، أوامر تبدأ بشرطة مائلة وإجراءات الرسائل) أو معاينات الروابط.

   5. ضمن مستوى العرض، اختَر إتاحة تطبيق Chat هذا لمستخدمين ومجموعات محدّدة وأدخِل عناوين البريد الإلكتروني للأفراد أو مجموعات Google في مؤسستك على Google Workspace:

      • لتثبيت تطبيقك واختباره بنفسك، أدخِل عنوان بريدك الإلكتروني.
      • لمشاركة تطبيق Chat داخلي مع فريق أو مؤسستك بأكملها بدون نشره في Marketplace، أدخِل مجموعة واحدة أو أكثر من "مجموعات Google". لا يوجد حدّ أقصى لعدد أعضاء المجموعات. إذا كان تطبيقك يطلب نطاقات chat.app.*، يجب عليك نشر التطبيق لموافقة المشرف.
      • إذا حصر المشرف عمليات تثبيت Marketplace بالتطبيقات المدرَجة في قائمة مسموح بها، سيحدّ Google Cloud Console من هذا الحقل ليشمل خمسة عناوين بريد إلكتروني فردية للمستخدمين لأغراض التطوير. لا ينطبق ظهور المجموعة إلا بعد أن يضيف المشرف التطبيق إلى القائمة المسموح بها.

6. اختياري: ضِمن السجلّات، ضَع علامة في المربّع تسجيل الأخطاء في Logging لاستخدام Google Cloud Logging. لمزيد من المعلومات، يُرجى الاطّلاع على المقالة سجلّات أخطاء طلب البحث عن تطبيقات Chat.

7. انقر على حفظ.

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

ضبط تطبيق Chat باستخدام واجهة برمجة التطبيقات لإضافات Google Workspace

بدلاً من ضبط تطبيق Chat يدويًا في "وحدة تحكّم Google Cloud"، يمكنك استخدام مشروعك على السحابة الإلكترونية على Google Cloud المسجَّل في برنامج معاينة المطوّر في Google Workspace لقراءة وضبط إعدادات تطبيق Chat الذي تم إنشاؤه كإضافة في Google Workspace برمجيًا باستخدام المورد chatAppConfig في Google Workspace add-ons API.

‫chatAppConfig هو مورد أحادي يتوفّر دائمًا لكل مشروع على السحابة الإلكترونية. قبل حفظ الإعدادات للمرة الأولى، يحتوي المورد على إعدادات فارغة (وهذا أيضًا ما يعرضه GetChatAppConfig إذا قرأت المورد قبل الحفظ الأول). بما أنّ المورد موجود من قبل، لن تحتاج إلى إنشائه بشكل منفصل، بل يمكنك استخدام UpdateChatAppConfig لحفظ الإعدادات الأولية وتعديل الإعدادات الحالية.

المتطلبات الأساسية والمصادقة

قبل استدعاء GetChatAppConfig أو UpdateChatAppConfig، يجب استيفاء المتطلبات الأساسية التالية:

1. سجِّل مشروعك على Google Cloud في برنامج معاينة المطوّرين في Google Workspace.
2. فعِّل واجهة برمجة تطبيقات إضافات Google Workspace (gsuiteaddons.googleapis.com) في مشروعك على السحابة الإلكترونية. يمكنك اختياريًا تفعيل Google Chat API (chat.googleapis.com) إذا أردت الاطّلاع على إعدادات تطبيق Chat أو تعديلها في وحدة تحكّم Google Cloud أو طلب Google Chat API.
3. يجب المصادقة كمستخدم بشري باستخدام بيانات اعتماد OAuth 2.0 التي تتضمّن نطاق https://www.googleapis.com/auth/cloud-platform. لا تتوفّر مصادقة حساب الخدمة لطُرق chatAppConfig.
4. تأكَّد من أنّ المستخدم الذي تمّت مصادقته لديه أذونات "إدارة الهوية وإمكانية الوصول" (IAM) المطلوبة في المشروع المستهدَف على السحابة الإلكترونية:
   • gsuiteaddons.chatAppConfigs.get وchat.bots.get لقراءة الإعدادات (GetChatAppConfig).
   • gsuiteaddons.chatAppConfigs.update وchat.bots.update لتعديل الإعدادات (UpdateChatAppConfig).
5. إذا كنت تستخدم مكتبة برامج، نزِّل مكتبة برامج "معاينة المطوّر" باستخدام حساب "معاينة المطوّر" المسجَّل.

تعديل إعدادات تطبيق Chat

لإعداد تطبيق Chat لأول مرة أو تعديل إعدادات حالية، أرسِل طلب PATCH (UpdateChatAppConfig) إلى مورد سينغلتون chatAppConfig لمشروعك على السحابة الإلكترونية:

• عند الحفظ الأولي لمشروع على السحابة الإلكترونية يحتوي على chatAppConfig فارغ، يجب إدخال displayName (من 3 إلى 25 حرفًا) وdescription (من حرف واحد إلى 40 حرفًا). في حال حذف interactiveFeatureConfig عند الحفظ الأولي، يتم ضبط تطبيق Chat على أنّه غير تفاعلي.
• بالنسبة إلى التعديلات اللاحقة، استخدِم مَعلمة طلب البحث الاختيارية updateMask لتحديد الحقول المفصولة بفواصل المطلوب تعديلها (أو احذف updateMask لتعديل جميع الحقول المقدَّمة). يؤدي تعديل حقل متكرّر (appCommands أو urlPatterns أو allowlistedTestingPrincipals) إلى استبدال القائمة بأكملها.

PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

استبدِل ما يلي في عنوان URL للطلب والترويسة والنص:

• ‫PROJECT_NUMBER: رقم المشروع الرقمي لمشروع Cloud الذي يستضيف تطبيق Chat
• ACCESS_TOKEN: رمز دخول OAuth 2.0 الخاص بالمستخدم والمصرَّح به باستخدام نطاق https://www.googleapis.com/auth/cloud-platform.
• ‫USER_EMAIL: عنوان بريد إلكتروني أو مجموعة Google من مؤسستك على Google Workspace لإضافتها إلى القائمة المسموح بها لاختبار تطبيق Chat (على سبيل المثال، عنوان بريدك الإلكتروني).
• حقول الإعدادات في نص الطلب (مثل displayName وdescription وavatarUri وinteractiveFeatureConfig، بما في ذلك إعدادات نقطة النهاية والأوامر وأنماط عناوين URL لمعاينة الروابط ومبادئ الاختبار) مع قيم تطبيق Chat. للحصول على تفاصيل حول جميع الحقول المتوافقة وخيارات نقاط النهاية، يُرجى الاطّلاع على مرجع REST لـ projects.chatAppConfig وprojects.chatAppConfig.patch.

الحصول على إعدادات تطبيق Chat

لقراءة الإعدادات الحالية لتطبيق Chat في مشروع على السحابة الإلكترونية، يمكنك طلب GetChatAppConfig. يمكنك تمرير مَعلمة طلب البحث الاختيارية view (ChatAppConfigView):

• BASIC (تلقائي): تعرض البيانات الوصفية الأساسية بدون interactiveFeatureConfig.
• ‫FULL: تعرض جميع حقول الإعدادات، بما في ذلك interactiveFeatureConfig.

إذا لم يتم حفظ إعدادات تطبيق Chat لمشروع على السحابة الإلكترونية بعد، ستعرض الطريقة عنصر ChatAppConfig فارغًا.

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

اعتبارات بشأن إضافات Google Workspace الحالية

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

• يجب أن يتمكّن كل من الأفراد ومشرفي حسابات Google Workspace من تثبيت الإضافة من Marketplace. يمكنك ضبط إعدادات التثبيت هذه في حزمة تطوير البرامج (SDK) في Marketplace.
• لا تستخدم تطبيقات Chat الاسم والشعار اللذين تضبطهما لتطبيقات Google Workspace الأخرى في عنصر addons.common البيان.
• بالنسبة إلى الإضافات المنشورة في Google Workspace Marketplace، لا يمكنك حفظ مسودة لأي تغييرات على إعدادات ضبط Google Chat API. بعد تعديل إعدادات ضبط Chat API وحفظها، يصبح تطبيق Chat المعدَّل متاحًا على الفور لجميع المستخدمين الحاليين. لتعديل بطاقة بياناتك على Marketplace، يمكنك إنشاء مسودة قبل إرسال أي تغييرات.
• إذا أنشأت الإضافة باستخدام "برمجة تطبيقات Google":
  • يجب استخدام معرّف نشر "برمجة تطبيقات Google" نفسه الذي تستخدمه لبقية إعدادات الإضافة.
  • لا يمكنك استخدام محرِّر "برمجة تطبيقات Google" لتثبيت عمليات النشر الاختبارية في Chat. بدلاً من ذلك، عليك تثبيتها مباشرةً من واجهة مستخدم Chat.
• إذا أنشأت الإضافة باستخدام خدمة HTTP، يُرجى حذف أي تفاصيل لإعداد تطبيق Chat في ملف بيان projects.deployments الذي تنشئه باستخدام واجهة برمجة تطبيقات إضافات Google Workspace. لا تُستخدم عمليات نشر HTTP التي تحدّدها في حزمة تطوير البرامج (SDK) في Google Workspace Marketplace إلا لتطبيقات Google Workspace الأخرى. بدلاً من ذلك، يمكنك ضبط تطبيق Chat في Google Cloud Console أو باستخدام المورد chatAppConfig في واجهة برمجة التطبيقات لإضافات Google Workspace.

منح مستخدمين آخرين الإذن بضبط Chat API

يمكنك منح مستخدمين محدّدين إذن الوصول إلى صفحة إعدادات تطبيق Chat من خلال منحهم دور مالك تطبيقات Chat أو دور مُشاهد تطبيقات Chat في "إدارة الهوية وإمكانية الوصول" (IAM) في Google Cloud. لا يمكن للمستخدمين الذين لديهم هذه الأدوار الانتقال إلى صفحة إعدادات تطبيقات Chat باستخدام لوحة بيانات واجهات برمجة التطبيقات والخدمات، ولكن يمكنهم الوصول إلى صفحة الإعدادات من خلال الانتقال إلى Google Cloud Console لمشروع على السحابة الإلكترونية المضيف لتطبيق Chat على النحو التالي:

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

حيث يمثّل PROJECT_ID رقم تعريف مشروع Google Cloud الذي يستضيف تطبيق Chat.

المواضيع ذات الصلة

• اختيار بنية تطبيق Chat
• تلقّي تفاعلات المستخدمين والردّ عليها
• اختبار الميزات التفاعلية لتطبيقات Google Chat