تحويل تطبيق تفاعلي في Google Chat إلى إضافة Google Workspace

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

من خلال التحويل، يمكن لتطبيق Google Chat استخدام إطار عمل إضافات Google Workspace، ما يتيح إمكانات جديدة للدمج والميزات داخل Google Chat وفي جميع أنحاء Google Workspace. على سبيل المثال، بدلاً من توزيعَين، أحدهما لتطبيق Google Chat والآخر لإضافة Google Workspace، يمكنك توزيع إضافة واحدة من Google Workspace من خلال Google Workspace Marketplace، وتعمل هذه الإضافة على توسيع نطاق تطبيقات Chat إلى جانب تطبيقات Google Workspace المضيفة الأخرى، مثل Gmail و"تقويم Google" و"مستندات Google".

القيود

قبل بدء عملية التحويل، راجِع قيود إضافات Google Workspace التي توسّع نطاق Google Chat للتأكّد من إمكانية تحويل تطبيق Google Chat بدون فقدان الوظائف الأساسية.

الخطوة 1: نسخ رمز تطبيق Google Chat الحالي

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

برمجة التطبيقات

  1. افتح مشروع Google Apps Script الحالي في تطبيق Google Chat.
  2. في يمين الصفحة، انقر على نظرة عامة .
  3. على يسار الصفحة، انقر على إنشاء نسخة .
  4. على يمين الصفحة، انقر على إعدادات المشروع .
  5. ضمن مشروع Google Cloud، انقر على تغيير المشروع.
  6. أدخِل رقم المشروع نفسه المرتبط بمشروع تطبيق Google Chat الحالي.
  7. انقر على تحديد المشروع.

HTTP

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

إذا تم نشر تطبيقك على Google Cloud وكان يعتمد على ميزات مرتبطة بمشروع Google Cloud (على سبيل المثال، هوية App Engine التلقائية)، يجب نشر الرمز الجديد على خدمة مرتبطة بمشروع تطبيق Google Chat الحالي.

الخطوة 2: تعديل الرمز البرمجي الذي تم نسخه

تستخدم إضافات Google Workspace التي توسّع نطاق استخدام Google Chat بنى مختلفة للطلبات والاستجابات مقارنةً بتطبيقات Google Chat التي تم إنشاؤها باستخدام أحداث التفاعل في Chat API. عليك تعديل الرمز البرمجي لاستخدام إضافة Google Workspace EventObject بدلاً من Event واجهة برمجة التطبيقات Google Chat لإرسال الطلبات وتلقّي الردود. استخدِم دليل تحويل الرموز لتعديل الرمز.

الخطوة 3: تفعيل إعدادات إضافة Google Workspace للمستخدمين التجريبيين

استخدِم Google Cloud Console لضبط إعدادات إضافة Google Workspace لتطبيق Google Chat:

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

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

  2. ضمن الميزات التفاعلية، انقر على التحويل إلى إضافة.

  3. فعِّل تفعيل إعدادات ضبط الإضافات.

  4. في قسم مستوى الرؤية، أضِف عناوين البريد الإلكتروني للمستخدمين التجريبيين.

  5. إذا لزم الأمر، عدِّل إعدادات الاتصال باستخدام عنوان URL لنقطة نهاية النشر أو معرّف نشر Apps Script لرمز تطبيق Google Chat الذي نسخته وعدّلته في الخطوة 2.

  6. انقر على حفظ واختبار.

الخطوة 4: اختبار التطبيق المحوَّل

اختبِر وظائف إضافة Google Workspace بشكل كامل باستخدام حسابات المستخدمين التجريبيين التي تم ضبطها في الخطوة 3. تحقَّق من جميع الميزات والتفاعلات.

الخطوة 5: إكمال عملية التحويل لجميع المستخدمين

بعد التأكّد من أنّ إضافة Google Workspace المحوَّلة تعمل بشكل صحيح، يمكنك إتاحتها لجميع المستخدمين.

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

    الانتقال إلى صفحة إعدادات واجهة برمجة تطبيقات Google Chat

  2. ضمن الميزات التفاعلية، انقر على التحويل إلى إضافة. يتم فتح لوحة جانبية.

  3. في اللوحة الجانبية، انقر على التحويل إلى إضافة.

  4. اكتب رقم تعريف مشروعك وانقر على تحويل.

أصبح تطبيق Google Chat الآن إضافة إلى Google Workspace توسّع نطاق Google Chat.

اختياري: تنظيف موارد Google Cloud غير المستخدَمة أو إتاحتها

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

دليل تحويل الرموز

يوضّح هذا القسم عملية الربط بين تنسيق تفاعل واجهة برمجة التطبيقات في Google Chat Event وتنسيق إضافة Google Workspace EventObject.

ربط الطلبات

يوضّح الجدول التالي كيفية ربط الحقول في Google Chat API Event بالحقول المقابلة في إضافة Google Workspace EventObject.

حقل Event التفاعل مع Google Chat API حقل EventObject لإضافة Google Workspace ملاحظات
action.actionMethodName لا ينطبق بالنسبة إلى تفاعلات البطاقة، يمكن تمرير اسم الطريقة كمَعلمة في commonEventObject.parameters. اطّلِع على فتح مربّع حوار أولي.
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 تتوفّر في حمولات مختلفة حسب نوع الحدث.
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 تتوفّر في حمولات مختلفة حسب نوع الحدث.
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 تتوفّر في حمولات مختلفة حسب نوع الحدث.
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 تتوفّر في حمولات مختلفة حسب نوع الحدث.
space
  • chat.messagePayload.space
  • chat.addedToSpacePayload.space
  • chat.removedFromSpacePayload.space
  • chat.buttonClickedPayload.space
  • chat.widgetUpdatedPayload.space
  • chat.appCommandPayload.space
thread
  • chat.messagePayload.message.thread
  • chat.buttonClickedPayload.message.thread
  • chat.appCommandPayload.message.thread
 تتوفّر في حمولات مختلفة حسب نوع الحدث.
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 تتوفّر في حمولات مختلفة حسب نوع الحدث.
token لا ينطبق تتم معالجة عملية إثبات الملكية بشكل مختلف، لذا يُرجى الاطّلاع على طلب إثبات ملكية تطبيقات HTTP.
type لا ينطبق يمكن استنتاج نوع الحدث من المشغّل.
user chat.user

طلب الربط حسب حالة الاستخدام

يوضّح الجدول التالي الاختلافات في حمولات الطلبات لحالات الاستخدام الشائعة بين تطبيقات Google Chat التي تم إنشاؤها باستخدام أحداث التفاعل مع Chat API وإضافات Google Workspace التي توسّع نطاق Google Chat.

حالة الاستخدام تفاعل واجهة برمجة التطبيقات للدردشة Event الحمولة حمولة إضافة Google Workspace EventObject
تمت إضافة التطبيق إلى المساحة 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
إزالة تطبيق من المساحة 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
إشارة المستخدم إلى تطبيق باستخدام @ 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
يشير المستخدم إلى تطبيق باستخدام @ لإضافته إلى المساحة عليك التعامل مع طلب واحد من Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 يجب التعامل مع طلبَين من Google Chat.

الطلب الأول:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

الطلب الثاني:
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
أمر يبدأ بشرطة مائلة 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
أمر يبدأ بشرطة مائلة لإضافة تطبيق إلى المساحة عليك التعامل مع طلب واحد من Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 يجب التعامل مع طلبَين من Google Chat.

الطلب الأول:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

الطلب الثاني:
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
ينقر المستخدم على زر في بطاقة أو مربّع حوار 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

بالنسبة إلى أحداث مربّع الحوار، يحتوي common.formInputs على قيم عناصر واجهة المستخدم. مثال على Google Apps Script:

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

بالنسبة إلى أحداث مربّع الحوار، يحتوي commonEventObject.formInputs على قيم عناصر واجهة المستخدم. مثال على Google Apps Script:

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
يرسل المستخدم معلومات في بطاقة الصفحة الرئيسية للتطبيق 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
يستدعي المستخدم أمر تطبيق باستخدام أمر سريع 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
معاينة الرابط 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
يعدّل المستخدم أداة في رسالة بطاقة أو مربّع حوار 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

ربط الردود بحالات الاستخدام

تعرض إضافات Google Workspace التي توسّع Google Chat إجراءات بدلاً من كائن Message. يوضّح الجدول التالي أنواع الردود Message في Google Chat API وما يقابلها من إجراءات في إضافات Google Workspace.

حالة الاستخدام ردّ Google Chat API Message رد إضافة Chat في Google Workspace
إنشاء رسالة في المساحة التي تم استدعاؤها 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

actionResponse هو حقل اختياري. لمزيد من المعلومات، يمكنك الاطّلاع على الردّ على أمر يبدأ بشرطة مائلة.

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

لمزيد من المعلومات، يُرجى الاطّلاع على إرسال رسالة.
تعديل رسالة 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

لمزيد من المعلومات، اطّلِع على تعديل رسالة (Chat).

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

لمزيد من المعلومات، اطّلِع على تعديل رسالة (إضافات).
معاينة الرابط 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

لمزيد من المعلومات، راجِع معاينة رابط (Chat).

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

لمزيد من المعلومات، يُرجى الاطّلاع على معاينة رابط(إضافات).
فتح مربّع حوار أولي 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

لمزيد من المعلومات، راجِع فتح مربّع حوار (Chat).

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
يمكن أن تحتوي البطاقة التي تدفعها على تطبيقات مصغّرة تتضمّن onClick إجراءات. بالنسبة إلى إضافات Google Workspace التي تستخدم بروتوكول HTTP، اضبط الإجراءات التالية لاستدعاء نقطة نهاية دالة: 
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

لمزيد من المعلومات، يُرجى الاطّلاع على فتح مربّع حوار (الإضافات).
إغلاق مربّع حوار 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

لمزيد من المعلومات، راجِع إغلاق مربّع حوار (Chat).

 
{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

لمزيد من المعلومات، يُرجى الاطّلاع على إغلاق مربّع حوار (الإضافات).
الاتصال بنظام خارجي (طلب الإعداد) 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

لمزيد من المعلومات، اطّلِع على الربط بنظام خارجي.

 
{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

لمزيد من المعلومات، يُرجى الاطّلاع على ربط إضافة Google Workspace بخدمة خارجية.
إكمال العناصر تلقائيًا في التطبيقات المصغّرة التفاعلية 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

لمزيد من المعلومات، يُرجى الاطّلاع على إضافة قائمة اختيار متعدّد.

 
{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

لمزيد من المعلومات، يُرجى الاطّلاع على جمع المعلومات ومعالجتها من مستخدمي Google Chat.

التعامل مع تفاعلات البطاقات في الرسائل التي تم إنشاؤها قبل التحويل

عند تحويل تطبيق Google Chat يستخدِم بروتوكول HTTP إلى إضافة Google Workspace، تتطلّب تفاعلات البطاقات في الرسائل التي تم إنشاؤها قبل التحويل معالجة خاصة. تستخدِم إضافات Google Workspace عنوان URL كاملاً عبر HTTP لعنصر action.function في البطاقة، بينما تستخدِم تطبيقات Google Chat التي تم إنشاؤها باستخدام أحداث التفاعل في Google Chat API اسم دالة. يلخّص الجدول التالي هذه الاختلافات.

تطبيق Google Chat الذي تم إنشاؤه باستخدام أحداث التفاعل في Google Chat API إضافة Google Workspace التي توسّع نطاق Google Chat
الإعداد يمكنك ضبط نقطة نهاية واحدة لجميع الأحداث في Google Cloud Console. عند تنفيذ تفاعلات البطاقات، لا تحتوي action البطاقة إلا على اسم الدالة المطلوب تنفيذها. يتم استدعاء نقطة نهاية HTTP الشائعة لأحداث النقر على البطاقة.

لمزيد من المعلومات، راجِع فتح مربّع حوار (Chat).



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 يمكنك اختياريًا ضبط نقاط نهاية لكل حدث في Google Cloud Console، ولكن لا يشمل ذلك أحداث النقر على البطاقة. عند تنفيذ تفاعلات البطاقة، يجب أن يحتوي action للبطاقة على عنوان URL الكامل لنقطة نهاية HTTP التي سيتم استدعاؤها. يمكنك ضبط نقطة نهاية HTTP فريدة لكل زر، أو استخدام نقطة نهاية مشتركة وتمرير الإجراء كمَعلمة في action.parameters.

لمزيد من المعلومات، يُرجى الاطّلاع على فتح مربّع حوار (الإضافات).



{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

لضمان عمل تفاعلات البطاقات مع الرسائل التي تم إنشاؤها قبل عملية التحويل، اضبط عنوان URL لتفاعل البطاقة في صفحة إعدادات Google Chat API.

يتم استخدام عنوان URL هذا فقط للتفاعلات مع الرسائل التي تم إنشاؤها قبل تحويل تطبيقك. وعندما يتفاعل مستخدم مع إحدى هذه الرسائل، يتم تمرير قيمة action.function الأصلية كمَعلمة باسم __action_method_name__.

مثال: النقر على البطاقة

إذا ضبطت عنوان URL لتفاعل البطاقة على https://.../card-interaction-handler، ونقر مستخدم على بطاقة في رسالة سابقة مع اتّخاذ الإجراء التالي:

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

يتم تسليم حدث إلى عنوان URL لتفاعل البطاقة الذي تم ضبطه بالتنسيق التالي:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

مثال: قائمة تحديد عناصر متعددة

إذا تفاعل مستخدم مع قائمة اختيار متعدّد تتضمّن مصدر بيانات خارجيًا:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

يتم تسليم حدث إلى عنوان URL لتفاعل البطاقة الذي تم ضبطه بالتنسيق التالي:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

في حال تفعيل خيار استخدام عنوان URL لنقطة نهاية HTTP الشائعة لجميع المشغّلات لمشغّلات HTTP، سيتم أيضًا استخدام عنوان URL الشائع لأحداث النقر على الزر.

التحقّق من طلبات إضافات Google Workspace التي تستخدم بروتوكول نقل النص الفائق (HTTP) وتوسّع نطاق Chat

بالنسبة إلى تطبيقات Google Chat المستندة إلى HTTP، يجب تعديل منطق التحقّق من أنّ الطلبات صادرة من Google عند تحويلها إلى إضافة Google Workspace.

في ما يلي الاختلافات الرئيسية في عملية التحقّق من الطلبات:

نوع التطبيق الجمهور المستهدَف البريد الإلكتروني لحساب الخدمة
تطبيق Google Chat الذي تم إنشاؤه باستخدام أحداث التفاعل في Google Chat API رقم المشروع chat@system.gserviceaccount.com
إضافة Google Workspace التي توسّع نطاق Google Chat نقطة نهاية HTTP فقط البريد الإلكتروني لحساب الخدمة لكل مشروع

يمكنك العثور على عنوان البريد الإلكتروني الفريد لحساب الخدمة الخاص بإضافة Google Workspace في قسم التحويل إلى إضافات Google Workspace في صفحة إعداد Google Chat API في Google Cloud Console.

لإثبات صحة الطلبات في إضافة Google Workspace التي تمت ترقيتها، اتّبِع الخطوات التالية:

  1. في حال استخدام وظائف Cloud Run، امنح دور roles/cloudfunctions.invoker لحساب الخدمة لكل إضافة. راجِع مقالة تفويض الوصول باستخدام "إدارة الهوية وإمكانية الوصول".
  2. عدِّل رمز التحقّق من الرمز المميّز لاستخدام عنوان البريد الإلكتروني لحساب خدمة إضافة Google Workspace من أجل التحقّق من توقيع الرمز المميّز لحامل الإذن. اطّلِع على التحقّق من صحة الطلبات الواردة من Google.