يتطلّب كل تطبيق 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 يظهر عندما يبحث المستخدمون عن تطبيقات في Chat | ما يصل إلى 40 حرفًا أبجديًا رقميًا |
| وصف طويل | اختيارية: وصف لما يمكن أن يفعله تطبيق Chat، ويظهر عندما يبدأ المستخدمون محادثة مع تطبيق Chat أو يفتحون الصفحة الرئيسية للجلسات لوكيل. لا تتوفّر هذه الميزة حاليًا إلا عند تعديل إعدادات التطبيق باستخدام وحدة تحكّم Google Cloud، وهي غير متاحة من خلال واجهة برمجة التطبيقات لإضافات Google Workspace. | 250 حرفًا كحدّ أقصى |
يتم عرض اسم تطبيق Chat وصورته الرمزية ووصفه للمستخدمين في واجهة مستخدم Chat. بالنسبة إلى بعض طلبات الكتابة في Chat API، يستخدم Chat هذه المعلومات لتحديد الإجراءات التي يتّخذها تطبيق Chat في Chat.
على سبيل المثال، إذا طلبت الطريقة spaces.create()، يتضمّن Chat اسم التطبيق في Chat في وصف من أنشأ المساحة، كما هو موضّح في الصورة التالية:
spaces.create() لإنشاء مساحة نيابةً عن مستخدم
للتفاعل مع تطبيقات Chat، يطّلع المستخدمون أيضًا على هذه المعلومات أو يستخدمونها بالطرق التالية:
- يمكنك الإشارة إلى تطبيق Chat باستخدام @ لإضافته إلى مساحة أو إرسال رسالة إليه.
- ابحث عن رسالة مباشرة مع تطبيق Chat وابدأها. في قائمة التطبيقات، تعرض الرسائل المباشرة اسم تطبيق Chat وصورته الرمزية.
- من خانة إدخال المحتوى، يمكن للمستخدمين تصفُّح تطبيقات Chat والاطّلاع على اسمها وصورة الأفاتار ووصفها.
ضبط إعدادات تطبيق Chat في Google Cloud Console
عندما تتوفّر لديك تفاصيل تطبيق Chat، افتح مشروعك على السحابة الإلكترونية واضبط Chat API:
في وحدة تحكّم Google Cloud، انتقِل إلى صفحة Chat API وانقر على صفحة الإعدادات:
ضمن معلومات التطبيق، املأ حقول اسم التطبيق وعنوان URL للأفاتار والوصف.
اختياري: املأ حقل الوصف الطويل.
اختياري: من قائمة بناء جملة الترميز، اختَر بناء جملة الترميز التلقائي (Markdown أو Chat) لرسائل تطبيق Chat. لمزيد من المعلومات حول تنسيق النص وكيفية تحديد Chat لبنية الترميز لطلبات البيانات من واجهة برمجة التطبيقات، يُرجى الاطّلاع على تنسيق الرسائل.
ضمن الميزات التفاعلية، يمكنك ضبط ما إذا كان تطبيق Chat يستجيب لتفاعلات المستخدمين:
لإنشاء تطبيق Chat تفاعلي، فعِّل تفعيل الميزات التفاعلية وأكمِل ما يلي:
- ضمن الوظائف:
- اختياري: اختَر إتاحة الصفحة الرئيسية للتطبيق لعرض بطاقة الصفحة الرئيسية في علامة التبويب الصفحة الرئيسية للرسائل المباشرة على الخاص مع تطبيق Chat.
- اختَر الانضمام إلى المساحات والمحادثات الجماعية لإتاحة تطبيق Chat للتثبيت والاستخدام. بشكل تلقائي، يمكن للمستخدمين تثبيت تطبيق Chat ومراسلته في مساحة مخصصة بين المستخدم وتطبيق Chat. يمكن للمستخدمين أيضًا إضافة تطبيق Chat والتفاعل معه في المساحات التي تضم عدة مستخدمين.
ضمن إعدادات الاتصال، اختَر البنية التي تريد استخدامها لتلقّي كائنات الأحداث من Chat:
- لاستخدام خدمة HTTP، اختَر عنوان URL لنقطة نهاية HTTP وأدخِل عنوان URL.
- لاستخدام مشروع "برمجة تطبيقات Google"، اختَر برمجة التطبيقات وقدِّم رقم تعريف النشر للمشروع.
- لاستخدام وكيل Dialogflow، اختَر Dialogflow، ثم اختَر Dialogflow CX أو Dialogflow ES، وقدِّم اسم المرجع الخاص بالوكيل.
- لاستخدام Pub/Sub، اختَر Cloud Pub/Sub وأدخِل اسم الموضوع.
اختياري: لتوجيه كائنات الأحداث إلى نقاط نهاية أو دوال محدّدة، انتقِل إلى إعدادات الاتصال > المشغّلات وقدِّم أو عدِّل نقاط نهاية عمليات الاستدعاء أو الدوال لمشغّلات Chat التالية:
- الصفحة الرئيسية للتطبيق (في حال تفعيل إتاحة الصفحة الرئيسية للتطبيق): يفتح المستخدم علامة التبويب الصفحة الرئيسية في رسالة مباشرة على الخاص مع تطبيق Chat.
- تمت الإضافة إلى المساحة: يضيف المستخدم تطبيق Chat إلى محادثة جماعية أو مساحة، أو يثبّت تطبيق Chat للرسائل بين شخصَين.
- رسالة: يرسل المستخدم رسالة إلى تطبيق Chat، مثلاً رسالة مباشرة أو إشارة باستخدام @إلى تطبيق Chat في مساحة تضم عدة مستخدمين.
- تمت الإزالة من المساحة: يشير هذا الحدث إلى أنّ أحد المستخدمين ألغى تثبيت تطبيق Chat أو أزاله من مساحة.
- أمر التطبيق: يستدعي المستخدم أمرًا سريعًا أو أمرًا يبدأ بشرطة مائلة أو إجراء رسالة من تطبيق Chat.
اختياري: يمكنك إضافة ميزات تفاعلية أخرى، مثل الجلسات أو الطلبات الأولية أو الأوامر (الأوامر السريعة، أوامر تبدأ بشرطة مائلة وإجراءات الرسائل) أو معاينات الروابط.
ضمن مستوى العرض، اختَر إتاحة تطبيق Chat هذا لمستخدمين ومجموعات محدّدة وأدخِل عناوين البريد الإلكتروني للأفراد أو مجموعات Google في مؤسستك على Google Workspace:
- لتثبيت تطبيقك واختباره بنفسك، أدخِل عنوان بريدك الإلكتروني.
- لمشاركة تطبيق Chat داخلي مع فريق
أو مؤسستك بأكملها بدون نشره في
Marketplace، أدخِل مجموعة واحدة أو أكثر
من "مجموعات Google". لا يوجد حدّ أقصى لعدد أعضاء المجموعات. إذا كان تطبيقك
يطلب نطاقات
chat.app.*، يجب عليك نشر التطبيق لموافقة المشرف. - إذا حصر المشرف عمليات تثبيت Marketplace بالتطبيقات المدرَجة في قائمة مسموح بها، سيحدّ Google Cloud Console من هذا الحقل ليشمل خمسة عناوين بريد إلكتروني فردية للمستخدمين لأغراض التطوير. لا ينطبق ظهور المجموعة إلا بعد أن يضيف المشرف التطبيق إلى القائمة المسموح بها.
- ضمن الوظائف:
اختياري: ضِمن السجلّات، ضَع علامة في المربّع تسجيل الأخطاء في Logging لاستخدام Google Cloud Logging. لمزيد من المعلومات، يُرجى الاطّلاع على المقالة سجلّات أخطاء طلب البحث عن تطبيقات Chat.
انقر على حفظ.
بعد حفظ الإعدادات، يمكن لأي مستخدم حدّدته في إعداد مستوى العرض في Chat API تثبيت تطبيق Chat أو اختباره أو استخدامه. لبدء اختبار تطبيق Chat وتصحيح أخطائه، يُرجى الاطّلاع على اختبار الميزات التفاعلية لتطبيقات Google Chat.
إعداد تطبيق Chat باستخدام واجهة سطر الأوامر في Google Cloud
بدلاً من استخدام وحدة تحكّم Google Cloud، يمكنك الاطّلاع على إعدادات تطبيق Chat وتعديلها من سطر الأوامر باستخدام واجهة سطر الأوامر في Google Cloud (gcloud CLI). على سبيل المثال، يمكنك ضبط تطبيق Chat من نص برمجي، أو الاحتفاظ بإعداداته في ملف تخزّنه مع الرمز البرمجي.
تتضمّن مجموعة الأوامر gcloud beta workspace-add-ons chat-app-config
الأوامر التالية:
تستخدم الأوامر المورد
chatAppConfig
في Google Workspace add-ons API.
قبل البدء
- ثبِّت gcloud CLI. إذا سبق لك تثبيت gcloud CLI، تأكَّد من استخدام أحدث إصدار من خلال تشغيل
gcloud components update. سجِّل الدخول إلى gcloud CLI باستخدام حساب المستخدم الخاص بك. لا تتيح الأوامر استخدام حسابات الخدمة.
gcloud auth loginاضبط مشروع السحابة الإلكترونية لتطبيق Chat كمشروع تلقائي لـ gcloud CLI. استخدِم رقم تعريف المشروع، لأنّ الأوامر لا تقبل رقم المشروع.
gcloud config set project PROJECT_IDبدلاً من ذلك، يمكنك إضافة العلامة
--projectإلى كل أمر.فعِّل واجهة برمجة تطبيقات إضافات Google Workspace في مشروع على السحابة الإلكترونية:
gcloud services enable gsuiteaddons.googleapis.comتأكَّد من حصولك على أدوار "إدارة الهوية وإمكانية الوصول" (IAM) التالية في مشروع على السحابة الإلكترونية:
- مطوّر إضافات Google Workspace
(
roles/gsuiteaddons.developer) لعرض الإعدادات وتعديلها، أو قارئ إضافات Google Workspace (roles/gsuiteaddons.reader) لعرضها فقط. وتشمل هذه الأدوار الأذونات المدرَجة في المتطلبات الأساسية والمصادقة. - مستهلك استخدام الخدمة
(
roles/serviceusage.serviceUsageConsumer): تستخدم واجهة سطر الأوامر gcloud مشروع على السحابة الإلكترونية كمشروع الحصة لطلباتها، ما يتطلب إذنserviceusage.services.use.
يتضمّن دورا المالك والمحرِّر كل هذه الأذونات. لا يكفي دورا مالك تطبيقات Chat ومشاهد تطبيقات Chat اللذان يمنحان إذن الوصول إلى صفحة الإعدادات في وحدة تحكّم Google Cloud.
- مطوّر إضافات Google Workspace
(
عرض الإعدادات
لعرض إعدادات تطبيق Chat، نفِّذ الأمر
describe:
gcloud beta workspace-add-ons chat-app-config describeتكون النتيجة مشابهة لما يلي:
avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
description: Helps manage tasks and schedules
displayName: Cymbal Assistant
errorLoggingEnabled: true
interactiveFeatureConfig:
allowlistedTestingPrincipals:
- user@example.com
appCommands:
- command: /help
commandId: 1
commandType: SLASH_COMMAND
description: Show available commands
connectionConfig:
httpEndpointConfig:
commonUrl: https://example.com/chat
supportsMultiuserSpaces: true
urlPatterns:
- hostPattern: example.com
pathPrefix: tasks/
name: projects/123456789012/chatAppConfig
state: ACTIVE
إذا لم يتضمّن مشروع على السحابة الإلكترونية تطبيق Chat
بعد، سينجح الأمر ويطبع فقط حقل name من
الإعدادات:
name: projects/123456789012/chatAppConfig
لتغيير الناتج، أضِف إحدى العلامات التالية:
-
--format=json: لطباعة الإعدادات بتنسيق JSON -
--view=basic: يتم استبعاد إعدادات الميزات التفاعلية (interactiveFeatureConfig). -
--format="value(displayName)": يطبع الاسم المعروض فقط، أو سطرًا فارغًا إذا لم يكن المشروع على السحابة الإلكترونية يتضمّن تطبيق Chat بعد. يحتوي تطبيق Chat الذي تم ضبطه دائمًا على اسم معروض، لذا يمكنك استخدام هذه العلامة في نص برمجي للتحقّق من توفّر تطبيق Chat.
تعديل الإعدادات
لضبط تطبيق Chat لأول مرة أو لتغيير إعداداته، شغِّل الأمر update. حدِّد الإعدادات باستخدام
العلامات أو في ملف إعداد. ولا يمكنك الجمع بينهما في أمر واحد.
في المرة الأولى التي يتم فيها تشغيل الأمر لمشروع على السحابة الإلكترونية، يجب تحديد اسم معروض ووصف على الأقل. ما لم تضبط الحالة على "غير مفعَّل"، سيكون تطبيق Chat نشطًا فور انتهاء الأمر. ويمكن للمستخدمين الذين تدرجهم كمختبِرين العثور على التطبيق واستخدامه.
استخدام العلامات
يضبط المثال التالي تطبيق Chat يتلقّى الأحداث في نقطة نهاية HTTP:
gcloud beta workspace-add-ons chat-app-config update \
--display-name="Quickstart App" \
--description="Quickstart app" \
--avatar-uri=https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png \
--http-endpoint-url=HTTP_ENDPOINT_URL \
--supports-multiuser-spaces \
--add-allowlisted-testing-principals=USER_EMAIL \
--error-logging-enabledغيِّر القيم في السلسلة على الشكل التالي:
-
HTTP_ENDPOINT_URL: عنوان URL الذي يستخدم HTTPS ويتلقّى كائنات الأحداث من Chat -
USER_EMAIL: عنوان البريد الإلكتروني لشخص أو مجموعة في مؤسستك على Google Workspace يمكنه تثبيت تطبيق Chat واختباره، مثل عنوان بريدك الإلكتروني
يطبع الأمر الإعدادات المعدَّلة.
يسرد الجدول التالي علامات الإعدادات في صفحة الإعدادات في Chat API ضمن Google Cloud Console. للحصول على تفاصيل حول كل علامة،
يُرجى الاطّلاع على
مرجع الأمر update.
| الإعداد في Google Cloud Console | أعلام |
|---|---|
| اسم التطبيق | --display-name |
| عنوان URL للأفاتار | --avatar-uri بعنوان URL يستخدم HTTPS لصورة تستوفي
متطلبات الأفاتار، أو
--clear-avatar-uri لاستخدام الأفاتار التلقائي |
| الوصف | --description |
| حالة التطبيق | --state=active أو --state=disabled |
| بنية الترميز | --markup-syntax=markdown أو
--markup-syntax=chat |
| الانضمام إلى المساحات والمحادثات الجماعية | --supports-multiuser-spaces أو
--no-supports-multiuser-spaces |
| إعدادات الربط | واحد ممّا يلي:
|
| مستوى الرؤية | --add-allowlisted-testing-principals
و--remove-allowlisted-testing-principals
و--clear-allowlisted-testing-principals |
| تسجيل الأخطاء في Logging | --error-logging-enabled أو
--no-error-logging-enabled |
لا تتضمّن الأوامر ومعاينات الروابط ونقاط النهاية المنفصلة لكل عامل تشغيل علامات. لضبطها، يمكنك استخدام ملف إعداد.
على سبيل المثال،
لإيقاف تطبيق Chat
بدون تغيير إعداداته الأخرى، نفِّذ الأمر التالي. لتفعيلها
مجددًا، استخدِم --state=active.
gcloud beta workspace-add-ons chat-app-config update --state=disabledاستخدام ملف إعداد
للاحتفاظ بالإعدادات في ملف أو لضبط الإعدادات التي لا تحتوي على علامات، يمكنك تمرير ملف YAML أو JSON إلى الأمر update. يستخدم الملف حقول مورد chatAppConfig، وهي الحقول نفسها التي يطبعها الأمر describe.
أنشئ ملفًا يحتوي على الإعدادات المطلوب تعديلها. على سبيل المثال، أنشئ ملفًا باسم
chat_app_config.yamlيتضمّن المحتوى التالي:displayName: Cymbal Assistant description: Helps manage tasks and schedules avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png state: ACTIVE errorLoggingEnabled: true interactiveFeatureConfig: supportsMultiuserSpaces: true connectionConfig: httpEndpointConfig: commonUrl: https://example.com/chat appCommands: - commandId: 1 commandType: SLASH_COMMAND command: /help description: Show available commands urlPatterns: - hostPattern: example.com pathPrefix: tasks/ allowlistedTestingPrincipals: - USER_EMAILاستبدِل
USER_EMAILبعنوان البريد الإلكتروني لمستخدم أو مجموعة في مؤسستك على Google Workspace يمكنها تثبيت تطبيق Chat واختباره.نفِّذ الأمر
updateباستخدام العلامة--config-file:gcloud beta workspace-add-ons chat-app-config update \ --config-file=chat_app_config.yaml
للبدء من الإعدادات الحالية لتطبيق Chat،
احفظ ناتج الأمر describe في ملف:
gcloud beta workspace-add-ons chat-app-config describe > chat_app_config.yamlبعد ذلك، عدِّل الملف واحذف الحقول التي لا تريد تغييرها، ثم مرِّر الملف إلى الأمر update. إذا كان الملف يحتوي على إعداد لا يمكن للأمر تعديله، سيتعذّر تنفيذ الأمر. لمعرفة التفاصيل، يُرجى الاطّلاع على القيود.
يتجاهل الأمر update الحقل name في الملف. يتم دائمًا تحديث
مشروع على السحابة الإلكترونية الذي حدّدته في gcloud CLI، لذا يمكنك استخدام
الملف نفسه لضبط تطبيق Chat في مشروع على السحابة الإلكترونية
آخر.
كيفية تطبيق الأمر للتغييرات
- يتم تغيير الإعدادات التي تحدّدها فقط. باستخدام العلامات، يغيّر الأمر إعدادات العلامات التي تمررها. باستخدام ملف الإعداد، يتم تغيير الحقول الموجودة في الملف، وبالتالي لا يحتاج الملف إلى أن يحتوي على الإعدادات بالكامل. تُعدّ إعدادات الاتصال استثناءً: يحلّ نوع الاتصال الذي تضبطه محلّ النوع الحالي، ويحلّ إصدار Dialogflow الذي تضبطه محلّ إعدادات Dialogflow بالكامل.
- يتم استبدال القوائم ككل. إذا كان الملف يحتوي على الحقل
appCommandsأوurlPatternsأوallowlistedTestingPrincipals، ستحل القائمة في الملف محل القائمة الحالية. لإضافة مختبِرين فرديين أو إزالتهم بدلاً من ذلك، استخدِم العلامتَين--add-allowlisted-testing-principalsو--remove-allowlisted-testing-principals. - تؤدي القيمة الفارغة إلى محو الإعداد. على سبيل المثال، يؤدي الملف الذي يحتوي على
urlPatterns: []ضمنinteractiveFeatureConfigإلى إزالة جميع أنماط عناوين URL لمعاينة الروابط. - لا يؤدي الأمر الذي يتعذّر تنفيذه إلى تغيير أي شيء. إذا كانت القيمة غير صالحة، سيطبع الأمر الخطأ ويترك الإعدادات كما هي.
- يتم فرض حدّ أقصى على معدّل الطلبات. تفرض واجهة برمجة التطبيقات حدًا أقصى لعدد طلبات القراءة وطلبات التعديل في الدقيقة لكل مشروع على السحابة الإلكترونية ولكل مؤسسة. يرسل كل أمر
updateطلب تعديل واحدًا. إذا أضفت مختبِرين أو أزلتهم باستخدام العلامات، يرسل الأمر أيضًا طلب قراءة. لتغيير عدة إعدادات، يمكنك تمريرها في أمر واحد أو ملف واحد بدلاً من تشغيل أمر لكل إعداد.
القيود
- لا تتيح الأوامر سوى تطبيقات Chat التي تم إنشاؤها كإضافات Google Workspace.
- لا تتوافق الأوامر مع حسابات الخدمة أو انتحال هوية حساب الخدمة. يجب تسجيل الدخول إلى gcloud CLI باستخدام حساب مستخدم.
- يحتوي مشروع على السحابة الإلكترونية على إعداد واحد لتطبيق Chat، ولا يمكن للأوامر حذفه. لمنع المستخدمين من استخدام تطبيق Chat، يمكنك ضبط حالته على "غير مفعَّل" أو حذف مشروع على السحابة الإلكترونية.
- يتم تطبيق التحديث على تطبيق Chat المنشور. لا تتضمّن الأوامر وضع المسودة أو التشغيل التجريبي.
- عندما يكون تطبيق Chat منشورًا أو قيد المراجعة في Google Workspace Marketplace، لا يمكن للأوامر تغيير اسمه المعروض أو صورته الرمزية أو وصفه أو أوامره أو أنماط عناوين URL لمعاينة الروابط.
- تتوافق الأوامر مع الإعدادات في مورد
chatAppConfig. لضبط إعداد لا يتضمّنه المورد، استخدِم وحدة تحكّم Google Cloud.
تحديد المشاكل وحلّها
إذا تعذّر تنفيذ أحد الأوامر، ابحث عن نص رسالة الخطأ في الجدول التالي. إذا بدأت الرسالة بحالة مثل INVALID_ARGUMENT، يعني ذلك أنّ
واجهة برمجة تطبيقات إضافات Google Workspace رفضت الطلب، ويصف النص بعد
الحالة المشكلة.
| تحتوي رسالة الخطأ على | السبب | الحل |
|---|---|---|
Invalid choice: 'chat-app-config' أو
Invalid choice: 'workspace-add-ons' |
لا يتضمّن الأمر beta، أو لا يتضمّن إصدار gcloud CLI الذي تستخدمه الأوامر. |
ابدأ الأمر بـ
gcloud beta workspace-add-ons chat-app-config. إذا استمرّ الخطأ، ثبِّت أحدث إصدار من gcloud CLI. |
PROJECT ID |
يتم ضبط المشروع على رقم مشروع. | اضبط المشروع على رقم تعريف المشروع. |
Failed to parse value(s) in protobuf |
يحتوي ملف الإعداد على حقل لا تتعرّف عليه gcloud CLI. تذكر رسالة الخطأ اسم الحقل. | قارِن اسم الحقل مع ناتج الأمر describe. إذا كان الحقل جديدًا، حدِّث gcloud CLI إلى أحدث إصدار. |
does not have permission to access projects instance |
رفضت واجهة برمجة التطبيقات الطلب. ويوضّح النص الذي يلي هذه الرسالة
السبب. مثال:
|
اطّلِع على المتطلبات في قسم قبل البدء. |
INVALID_ARGUMENT |
إحدى القيم غير صالحة. على سبيل المثال، يجب أن يتراوح طول الاسم المعروض بين 3 و25 حرفًا، وأن يتراوح طول الوصف بين حرف واحد و40 حرفًا. إذا
تضمّنت الرسالة not found or deleted، يعني ذلك أنّ رقم تعريف المشروع
غير صحيح. |
صحِّح القيمة التي تصفها رسالة الخطأ، ثم شغِّل الأمر مرة أخرى. |
FAILED_PRECONDITION |
لا يسمح تطبيق Chat بالطلب. على سبيل المثال، لم يتم إنشاؤه كإضافة في Google Workspace، أو تم نشره في Google Workspace Marketplace ولا يمكن تغيير الإعداد. | اتّبِع التعليمات الواردة في رسالة الخطأ. لإعداد تطبيق Chat ليس إضافة في Google Workspace، استخدِم وحدة تحكّم Google Cloud أو حوِّله إلى إضافة في Google Workspace. |
RESOURCE_EXHAUSTED أو 429 |
تلقّت واجهة برمجة التطبيقات عددًا كبيرًا جدًا من الطلبات لمشروع على السحابة الإلكترونية أو لمؤسستك في فترة زمنية قصيرة. | يُرجى الانتظار دقيقة، ثم تشغيل الأمر مرة أخرى. |
ضبط تطبيق Chat باستخدام واجهة برمجة التطبيقات لإضافات Google Workspace
بدلاً من ضبط تطبيق Chat يدويًا في
وحدة تحكّم Google Cloud، يمكنك قراءة الإعدادات وتعديلها آليًا
لتطبيق Chat تم إنشاؤه كإضافة في Google Workspace
باستخدام المورد chatAppConfig في
Google Workspace add-ons API.
chatAppConfig هو مورد أحادي يتوفّر دائمًا لكل مشروع على السحابة الإلكترونية. قبل حفظ الإعدادات للمرة الأولى، يحتوي المورد على إعدادات فارغة (وهذا أيضًا ما يعرضه GetChatAppConfig إذا قرأت المورد قبل الحفظ الأول). بما أنّ المورد
موجود من قبل، لن تحتاج إلى إنشائه بشكل منفصل، بل يمكنك استخدام
UpdateChatAppConfig
لحفظ الإعدادات الأولية وتعديل الإعدادات الحالية.
المتطلبات الأساسية والمصادقة
قبل استدعاء GetChatAppConfig أو UpdateChatAppConfig، يجب استيفاء
المتطلبات الأساسية التالية:
- فعِّل واجهة برمجة تطبيقات إضافات Google Workspace
(
gsuiteaddons.googleapis.com) في مشروعك على السحابة الإلكترونية. يمكنك اختياريًا تفعيل Google Chat API (chat.googleapis.com) إذا أردت الاطّلاع على إعدادات تطبيق Chat أو تعديلها في وحدة تحكّم Google Cloud أو طلب Google Chat API. - يجب المصادقة كمستخدم بشري باستخدام بيانات اعتماد OAuth 2.0 التي تتضمّن نطاق
https://www.googleapis.com/auth/cloud-platform. لا تتوفّر مصادقة حساب الخدمة لطُرقchatAppConfig. - تأكَّد من أنّ المستخدم الذي تمّت مصادقته لديه أذونات "إدارة الهوية وإمكانية الوصول" (IAM) المطلوبة في المشروع المستهدَف على السحابة الإلكترونية:
gsuiteaddons.chatAppConfigs.getوchat.bots.getلقراءة الإعدادات (GetChatAppConfig).-
gsuiteaddons.chatAppConfigs.updateوchat.bots.updateوchat.bots.getلتعديل الإعدادات (UpdateChatAppConfig).
- إذا كنت تستخدم مكتبة برامج عميل واجهة برمجة التطبيقات، ثبِّت أحدث إصدار من مكتبة برامج Google Workspace add-ons API للغتك. للحصول على قائمة بمكتبات العملاء، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات لإضافات Google Workspace.
تعديل إعدادات تطبيق 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 فارغًا.
HTTP
GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN
Node.js
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();
Python
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)
سقف الاستخدام
تتوفّر طرق chatAppConfig بحصص لكل مشروع. إذا تجاوزت حصة، سيتعذّر تنفيذ الطلب وسيظهر رمز حالة HTTP 429: Too many requests. للاطّلاع على حدود الحصة، يُرجى مراجعة حدود استخدام واجهة برمجة التطبيقات لإضافات Google Workspace.
تحديد الأخطاء وتصحيحها
إذا تعذّر تنفيذ طلب chatAppConfig، تحقَّق من رمز حالة HTTP والحقل message في استجابة الخطأ. يسرد الجدول التالي الأخطاء الشائعة وأسبابها وكيفية حلها.
| رمز حالة HTTP | الأسباب الشائعة | الدقة |
|---|---|---|
400: Bad Request (INVALID_ARGUMENT) |
|
تحقَّق من الحقل message بحثًا عن الحقل غير الصالح،
وصحِّح الطلب. للاطّلاع على الحقول والقيم المسموح بها، يُرجى مراجعة مرجع projects.chatAppConfig. |
400: Bad Request (FAILED_PRECONDITION) |
|
|
403: Forbidden (PERMISSION_DENIED) |
|
|
404: Not Found (NOT_FOUND) |
المشروع على السحابة الإلكترونية في اسم المورد غير موجود، أو لا يمكن للمستخدم الذي تمت مصادقته الوصول إليه. | يُرجى التأكّد من أنّ اسم المورد يستخدم رقم المشروع الصحيح بالتنسيق projects/PROJECT_NUMBER/chatAppConfig، ومن أنّ المستخدم لديه إذن بالوصول إلى المشروع على السحابة الإلكترونية. |
429: Too Many Requests (RESOURCE_EXHAUSTED) |
تم تجاوز الحصة المحدّدة لكل مشروع. | انتظِر وأعِد محاولة إجراء الطلب لاحقًا. لمعرفة الحدود القصوى، يُرجى الاطّلاع على الحدود القصوى للاستخدام. |
اعتبارات بشأن إضافات 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، باستخدام gcloud CLI، أو باستخدام الموردchatAppConfigفي Google Workspace add-ons API.
منح مستخدمين آخرين الإذن بضبط 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
تطبيقات Chat التي ليست إضافات: ضبط Google Chat API
إذا كنت تدير تطبيق Chat ليس إضافة في Google Workspace، سيستخدم إعدادك نقطة نهاية واحدة لجميع أحداث التفاعل بدلاً من المشغّلات لكل حدث:
في وحدة تحكّم Google Cloud، انتقِل إلى صفحة إعدادات Chat API:
ضمن الميزات التفاعلية، فعِّل تفعيل الميزات التفاعلية.
أزِل العلامة من المربّع إنشاء تطبيق Chat هذا كإضافة على Google Workspace. سيظهر مربّع حوار يطلب منك التأكيد. في مربّع الحوار، انقر على إيقاف.
ضمن الوظائف، اختَر إتاحة الصفحة الرئيسية للتطبيق أو الانضمام إلى المساحات والمحادثات الجماعية حسب الحاجة.
ضمن إعدادات الاتصال، حدِّد نقطة نهاية واحدة لتطبيق Chat (عنوان URL لنقطة نهاية HTTP أو معرّف نشر برمجة تطبيقات Google أو اسم موضوع Cloud Pub/Sub أو Dialogflow).
اضبط الإعدادات الاختيارية لكل من الطلبات والطلبات الأولية ومعاينات الروابط ومستوى العرض والسجلّات، ثم انقر على حفظ.
لترقية تطبيق في Chat ليس إضافة إلى إضافة Google Workspace التي توسّع Google Chat، يُرجى الاطّلاع على تحويل تطبيق في Google Chat إلى إضافة Google Workspace.