ضبط 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	ما يصل إلى 25 حرفًا أبجديًا رقميًا
عنوان URL للأفاتار	الصورة التي تظهر كأفاتار لتطبيق Chat	عنوان URL يستخدم HTTPS ويوجّه إلى صورة رسومات مربّعة (بتنسيق PNG أو JPEG). الحجم المقترَح هو 256 × 256 بكسل أو أكثر.
الوصف	وصف موجز للغرض من تطبيق Chat	ما يصل إلى 40 حرفًا أبجديًا رقميًا

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

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

الشكل 1 رسالة الإسناد التي يعرضها Chat عند استخدام طريقة spaces.create() لإنشاء مساحة نيابةً عن مستخدم

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

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

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

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

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

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

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

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

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

   ملاحظة: إذا كان تطبيق Chat يستدعي فقط واجهة برمجة تطبيقات 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 وأدخِل اسم الموضوع.
      تحذير: إذا تم ملء رقم تعريف نشر "برمجة تطبيقات Google"، يتم ربط مشروع على السحابة الإلكترونية بإضافة حالية على Google Workspace. في حال تعديل معرّف النشر في Chat API، يتم تعديل معرّف النشر للإضافة وقد يؤثر ذلك في بطاقة بياناتك في Google Workspace Marketplace. لمراجعة إعدادات الإضافة، يُرجى الاطّلاع على ضبط تطبيقك في حزمة تطوير البرامج (SDK) في Google Workspace Marketplace.

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

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

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

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

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

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

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

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

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

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

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

يمكنك منح مستخدمين محدّدين إذن الوصول إلى صفحة إعدادات تطبيق Chat من خلال منحهم دور مالك تطبيقات Chat أو دور مُشاهد تطبيقات Chat في Google Cloud Identity Access Management (IAM). لا يمكن للمستخدمين الذين لديهم هذه الأدوار الانتقال إلى صفحة إعدادات تطبيقات 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.

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

لا يمكن للمستخدمين الذين لديهم أدوار مخصّصة تتضمّن أذونات resourcemanager.projects.(get|update) الوصول إلى إعدادات تطبيق Chat. بالنسبة إلى الأدوار المخصّصة، استخدِم أذونات chat.bots.(get|update) بدلاً من ذلك.

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

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

تطبيقات Chat التي ليست إضافات: ضبط Google Chat API

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

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

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

2. ضمن الميزات التفاعلية، فعِّل تفعيل الميزات التفاعلية.

3. أزِل العلامة من المربّع إنشاء تطبيق Chat هذا كإضافة على Google Workspace. سيظهر مربّع حوار يطلب منك التأكيد. في مربّع الحوار، انقر على إيقاف.

4. ضمن الوظائف، اختَر إتاحة الصفحة الرئيسية للتطبيق أو الانضمام إلى المساحات والمحادثات الجماعية حسب الحاجة.

5. ضمن إعدادات الاتصال، حدِّد نقطة نهاية واحدة لتطبيق Chat (عنوان URL لنقطة نهاية HTTP أو معرّف نشر برمجة تطبيقات Google أو اسم موضوع Cloud Pub/Sub أو Dialogflow).

6. اضبط الإعدادات الاختيارية لكل من الأوامر ومعاينات الروابط ومستوى العرض والسجلّات، ثم انقر على حفظ.

لترقية تطبيق Chat ليس إضافة إلى إضافة Google Workspace التي توسّع Google Chat، يُرجى الاطّلاع على تحويل تطبيق Google Chat إلى إضافة Google Workspace.