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

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

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

القيود

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

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

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

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

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

HTTP

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

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

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

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

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

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

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

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

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

  3. ضمن التحويل إلى إضافة على Google Workspace، انقر على التحويل إلى إضافة.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

دليل تحويل الرموز البرمجية

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

تحديد مصدر الطلب

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

تطبيق Chat ليس إضافة (الحقل Event) حقل 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

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

يوضّح الجدول التالي الاختلافات في حمولات الطلبات لحالات الاستخدام الشائعة بين تطبيقات Chat التي ليست إضافات وإضافات 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":

{
  "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":

{
  "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 لتطبيق Chat ليس إضافة، مع ما يقابلها من إجراءات إضافات Google Workspace.

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

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

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

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

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

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

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

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

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

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

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة فتح مربّعات حوار تفاعلية.

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

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

لمزيد من المعلومات، يُرجى الاطّلاع على إغلاق مربّع حوار.

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

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

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

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

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

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

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

لمزيد من المعلومات، يُرجى الاطّلاع على قراءة بيانات النماذج التي أدخلها المستخدمون على البطاقات.

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

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

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

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة فتح مربّعات حوار تفاعلية.



{
  "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 الشائع لأحداث النقر على الزر.

التحقّق من طلبات إضافات HTTP في Google Workspace التي توسّع Chat

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

في ما يلي الاختلافات الرئيسية في عملية إثبات صحة الطلب:

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

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

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

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