تحويل تطبيق 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 المباشر، أنشئ نسخة من الرمز وعدِّلها.

الخطوة 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 التي ليست إضافات وإضافات Google Workspace التي توسّع نطاق Google Chat.

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

{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}

{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}

{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}

{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}

{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}

{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}

{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

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

{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

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

{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

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

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

{
  "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 غير الإضافات اسم دالة. يلخّص الجدول التالي هذه الاختلافات.

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

{
  "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 التي تستخدم بروتوكول HTTP وليست إضافات: التحقّق من أنّ الطلبات واردة من Google Chat
• التحقّق من بروتوكول HTTP لإضافات Google Workspace: التحقّق من الطلبات الواردة من Google

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

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

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

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