ضبط Google Chat API

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

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

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

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

اختيار اسم معروض وصورة رمزية ووصف لتطبيق 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 في وصف من أنشأ المساحة، كما هو موضّح في الصورة التالية:

ينشئ تطبيق Google 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. اختياري: املأ حقل الوصف الطويل.

  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 Cloud

بدلاً من استخدام وحدة تحكّم Google Cloud، يمكنك الاطّلاع على إعدادات تطبيق Chat وتعديلها من سطر الأوامر باستخدام واجهة سطر الأوامر في Google Cloud ‏(gcloud CLI). على سبيل المثال، يمكنك ضبط تطبيق Chat من نص برمجي، أو الاحتفاظ بإعداداته في ملف تخزّنه مع الرمز البرمجي.

تتضمّن مجموعة الأوامر gcloud beta workspace-add-ons chat-app-config الأوامر التالية:

  • describe: يعرض الإعدادات.
  • update: يتم إعداد تطبيق Chat للمرة الأولى أو تغيير إعداداته.

تستخدم الأوامر المورد chatAppConfig في Google Workspace add-ons API.

قبل البدء

  1. ثبِّت gcloud CLI. إذا سبق لك تثبيت gcloud CLI، تأكَّد من استخدام أحدث إصدار من خلال تشغيل gcloud components update.
  2. سجِّل الدخول إلى gcloud CLI باستخدام حساب المستخدم الخاص بك. لا تتيح الأوامر استخدام حسابات الخدمة.

    gcloud auth login
  3. اضبط مشروع السحابة الإلكترونية لتطبيق Chat كمشروع تلقائي لـ gcloud CLI. استخدِم رقم تعريف المشروع، لأنّ الأوامر لا تقبل رقم المشروع.

    gcloud config set project PROJECT_ID

    بدلاً من ذلك، يمكنك إضافة العلامة --project إلى كل أمر.

  4. فعِّل واجهة برمجة تطبيقات إضافات Google Workspace في مشروع على السحابة الإلكترونية:

    gcloud services enable gsuiteaddons.googleapis.com
  5. تأكَّد من حصولك على أدوار "إدارة الهوية وإمكانية الوصول" (IAM) التالية في مشروع على السحابة الإلكترونية:

    • مطوّر إضافات Google Workspace (roles/gsuiteaddons.developer) لعرض الإعدادات وتعديلها، أو قارئ إضافات Google Workspace (roles/gsuiteaddons.reader) لعرضها فقط. وتشمل هذه الأدوار الأذونات المدرَجة في المتطلبات الأساسية والمصادقة.
    • مستهلك استخدام الخدمة (roles/serviceusage.serviceUsageConsumer): تستخدم واجهة سطر الأوامر gcloud مشروع على السحابة الإلكترونية كمشروع الحصة لطلباتها، ما يتطلب إذن serviceusage.services.use.

    يتضمّن دورا المالك والمحرِّر كل هذه الأذونات. لا يكفي دورا مالك تطبيقات Chat ومشاهد تطبيقات Chat اللذان يمنحان إذن الوصول إلى صفحة الإعدادات في وحدة تحكّم Google Cloud.

عرض الإعدادات

لعرض إعدادات تطبيق 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
إعدادات الربط واحد ممّا يلي:
  • عنوان URL لنقطة نهاية HTTP: --http-endpoint-url
  • برمجة التطبيقات: --apps-script-deployment-id
  • ‫Cloud Pub/Sub: ‏--pubsub-topic مع موضوع في مشروع على السحابة الإلكترونية نفسه، بالتنسيق projects/PROJECT_ID/topics/TOPIC_ID
  • ‫Dialogflow: ‏--dialogflow-edition=es أو --dialogflow-edition=cx مع ضبط --dialogflow-agent على اسم المورد الخاص بالوكيل أو البيئة، مثل projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID
مستوى الرؤية ‫--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.

  1. أنشئ ملفًا يحتوي على الإعدادات المطلوب تعديلها. على سبيل المثال، أنشئ ملفًا باسم 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 واختباره.

  2. نفِّذ الأمر 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 رفضت واجهة برمجة التطبيقات الطلب. ويوضّح النص الذي يلي هذه الرسالة السبب. مثال:
  • لا يتضمّن حسابك أدوار "إدارة الهوية وإمكانية الوصول" المطلوبة. إذا كان النص يحتوي على Caller does not have required permission to use project، يعني ذلك أنّ دور "مستهلك استخدام الخدمة" غير متوفّر.
  • لم يتم تفعيل واجهة برمجة تطبيقات إضافات Google Workspace في مشروع على السحابة الإلكترونية.
  • إذا سجّلت الدخول باستخدام حساب خدمة
اطّلِع على المتطلبات في قسم قبل البدء.
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، يجب استيفاء المتطلبات الأساسية التالية:

  1. فعِّل واجهة برمجة تطبيقات إضافات Google Workspace (gsuiteaddons.googleapis.com) في مشروعك على السحابة الإلكترونية. يمكنك اختياريًا تفعيل Google Chat API (chat.googleapis.com) إذا أردت الاطّلاع على إعدادات تطبيق Chat أو تعديلها في وحدة تحكّم Google Cloud أو طلب Google Chat API.
  2. يجب المصادقة كمستخدم بشري باستخدام بيانات اعتماد OAuth 2.0 التي تتضمّن نطاق https://www.googleapis.com/auth/cloud-platform. لا تتوفّر مصادقة حساب الخدمة لطُرق chatAppConfig.
  3. تأكَّد من أنّ المستخدم الذي تمّت مصادقته لديه أذونات "إدارة الهوية وإمكانية الوصول" (IAM) المطلوبة في المشروع المستهدَف على السحابة الإلكترونية:
    • gsuiteaddons.chatAppConfigs.get وchat.bots.get لقراءة الإعدادات (GetChatAppConfig).
    • ‫gsuiteaddons.chatAppConfigs.update وchat.bots.update وchat.bots.get لتعديل الإعدادات (UpdateChatAppConfig).
  4. إذا كنت تستخدم مكتبة برامج عميل واجهة برمجة التطبيقات، ثبِّت أحدث إصدار من مكتبة برامج 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)
  • يحتوي "updateMask" على حقل غير متوفّر أو لا يمكن تعديله.
  • قيمة الحقل غير متوفّرة أو غير صالحة. على سبيل المثال، لا يتضمّن interactiveFeatureConfig connectionConfig.
تحقَّق من الحقل message بحثًا عن الحقل غير الصالح، وصحِّح الطلب. للاطّلاع على الحقول والقيم المسموح بها، يُرجى مراجعة مرجع projects.chatAppConfig.
400: Bad Request ‏(FAILED_PRECONDITION)
  • لم يتم إنشاء تطبيق Chat كإضافة في Google Workspace.
  • لا يمكن تغيير الحقل لأنّ تطبيق Chat منشور على Google Workspace Marketplace.
  • القيمة الجديدة غير متوافقة مع إعدادات تطبيق Chat الحالية.
  • حوِّل تطبيق Chat إلى إضافة Google Workspace، أو اضبطه في وحدة تحكّم Google Cloud.
  • اتّبِع التعليمات الواردة في الحقل message لتعديل بطاقة بيانات المتجر المنشورة.
  • يُرجى التحقّق من حقل message بحثًا عن الإعداد المتعارض، وتعديل كلا الإعدادَين في الطلب نفسه، أو تغيير الإعداد الحالي أولاً.
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":
  • إذا أنشأت الإضافة باستخدام خدمة 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 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.