تطوير تطبيق Chat باستخدام "برمجة التطبيقات"

"برمجة التطبيقات" هي إحدى أسرع الطرق لإنشاء تطبيق Chat في Google Chat.

• يمكنك تشغيل التطبيق في دقائق معدودة مباشرةً من متصفحك.
• لا تقلق بشأن تشغيل الخوادم وإدارتها، أو الصيانة المستمرة أو تكاليف التشغيل، أو حتى تنزيل بيئة إعداد وإعدادها.
• من السهل جدًا استدعاء واجهات Google APIs، خاصة Google Workspace واجهات برمجة التطبيقات، نظرًا لعدم وجود تنزيل أو إعداد، يتم التعامل مع المصادقة تلقائيًا، وتشبه طلبات Google API طلبات الوظائف الأصلية تمامًا.

يوضح هذا الدليل كيفية إنشاء تطبيق وتسجيله باستخدام برمجة التطبيقات.

البدء

يعرض لك هذا القسم كيفية إنشاء تطبيق Chat بسرعة باستخدام "برمجة التطبيقات".

الخطوة 1: نسخ نموذج برمجة التطبيقات

أسهل طريقة لبدء إنشاء تطبيق "برمجة تطبيقات Google" هي استخدام نموذج المحادثة. يؤدي هذا إلى إنشاء مشروع "برمجة تطبيقات Google" بالطرق التي تحتاجها. بعد ذلك، املأ الطرق كما هو مطلوب لتنفيذ منطق تطبيقك، أو للتكامل مع تطبيق أنشأته. تعرض الشفرة التالية مثالاً للنموذج الذي تمت تعبئته لتطبيق بسيط.

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  var name = "";

  if (event.space.type == "DM") {
    name = "You";
  } else {
    name = event.user.displayName;
  }
  var message = name + " said \"" + event.message.text + "\"";

  return { "text": message };
}

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAddToSpace(event) {
  var message = "";

  if (event.space.singleUserBotDm) {
    message = "Thank you for adding me to a DM, " + event.user.displayName + "!";
  } else {
    message = "Thank you for adding me to " +
        (event.space.displayName ? event.space.displayName : "this chat");
  }

  if (event.message) {
    // Bot added through @mention.
    message = message + " and you said: \"" + event.message.text + "\"";
  }

  return { "text": message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onRemoveFromSpace(event) {
  console.info("Bot removed from ",
      (event.space.name ? event.space.name : "this chat"));
}

الخطوة 2: تعديل دالة onMessage

تعرض الدالة onMessage في النموذج تلقائيًا الكائن Message الذي يحتوي على نص وبطاقة بسيطة. يمكنك تعديل هذه الدالة لعرض نص أو أدوات بطاقات معينة.

function onMessage(e) {
  return { 'text': 'You said: \`' + e.message.text + '\`' };
}

الخطوة 3: الحصول على رقم تعريف النشر

قبل أن تتمكّن من تسجيل تطبيقك، يجب الحصول على رقم تعريف النشر لهذا التطبيق المحدّد.

1. انقر على نشر > نشر جديد.
2. ضمن اختيار النوع، انقر على إضافة.
3. املأ الخيارات وانقر على نشر.
4. ضمن "معرّف النشر"، انقر على نسخ.

اطّلع على دليل إدارة الإصدارات للتعرّف على الممارسات المقترحة لاستخدام معرّفات النشر.

الخطوة 4: تسجيل التطبيق

يمكنك تسجيل تطبيقك من Google Cloud Console. على شاشة تسجيل التطبيق، أدخل اسم التطبيق وعنوان URL للصورة الرمزية والوصف. للاختبار، يمكنك تفعيل "يمكن إرسال رسالة مباشرةً إلى التطبيق" و"يعمل التطبيق في المساحات التي تتضمن عدة مستخدمين". ضمن إعدادات الاتصال، اختر "برمجة التطبيقات" والصق معرّف النشر الذي نسخته في الخطوة السابقة.

الخطوة 5: اختبار تطبيقك

لاختبار تطبيقك، يمكنك بدء رسالة مباشرة معه أو الإشارة إليه باستخدام الرمز @في مساحة. وعند التحدث إليه، سيستجيب مع أي رد على الرسالة في الخطوة 2. أكملت هذه الخطوة.

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

فعاليات

يدعم "برمجة التطبيقات" العديد من وظائف معالج الأحداث التي يمكن لتطبيقك تنفيذها. تعالج كل دالة نوع حدث مختلفًا، وتتلقّى كل دالة وسيطة واحدة e، وهي عبارة عن كائن حدث.

onAddToSpace(e)

يتم تنفيذ هذه الدالة عند إضافة تطبيقك إلى مساحة عمل. يمكن إضافة تطبيقك مباشرةً إلى مساحة العمل أو إضافته من خلال الإشارة باستخدام @. في الحالة الثانية، سيتضمّن الحدث e أيضًا السمة message. يجب أن تعرض هذه الدالة عنصر Message، والذي عادة ما يكون رسالة ترحيب لإعلام المستخدمين النهائيين بتطبيقك أو ردًا على الإشارة باستخدام الرمز @.

onMessage(e)

يتم استدعاء هذه الدالة عندما يكون تطبيقك موجودًا بالفعل في مساحة العمل ويذكر المستخدم @ تطبيقك. يجب أن تعرض كائن Message يحتوي على استجابة تطبيقك.

onRemoveFromSpace(e)

يتم استدعاء هذه الدالة عندما يزيل المستخدم تطبيقك من قائمة الرسائل المباشرة أو من مساحة عمل. يتم تجاهل القيمة الناتجة لهذه الدالة نظرًا لإزالة تطبيقك ولا يمكن نشر أي رسائل أخرى عليها.

ينفذ المثال التالي onAddToSpace وonRemoveFromSpace:

// onAddToSpace() is invoked when the app is added to a space or when
// a user initiates / re-initiates a direct message with the app.
function onAddToSpace(e) {
  if (!e.space.singleUserBotDm) {
    return { 'text': 'Thanks for adding me to "' +
        (e.space.displayName ? e.space.displayName : "this chat") + '"!' };
  } else {
    return { 'text': 'Thanks for adding me to a DM!' };
  }
}
// onRemoveFromSpace() is invoked when app is removed from a space
// or when a user removes a direct message with the app.
function onRemoveFromSpace(e) {}

يرجى ملاحظة أن e.space.displayName قد لا يكون موجودًا في الرسائل المباشرة بين البشر.

البطاقات التفاعلية

مثل التطبيقات الأخرى، يمكن لتطبيقات برمجة التطبيقات عرض البطاقات التفاعلية. للتعرف على كيفية جعل البطاقات تفاعلية، اطلع على المستندات على البطاقات التفاعلية. يكمن الاختلاف الرئيسي في تطبيقات "برمجة التطبيقات" في أنه يمكنها تحديد طريقة معيّنة لاستدعاءها عند تشغيل حدث onClick باستخدام action.actionMethodName وزوج العمل /parameter.parameters للمفتاح/القيمة كمعلمات للطريقة.

التفويض

تحتاج تطبيقات برمجة التطبيقات التي يمكنها الدخول إلى الموارد المحمية إلى مطالبة المستخدمين بتفويض هذا الدخول في المرة الأولى التي يتم تشغيله فيها لكل مستخدم. ولا يتطلب هذا أي إجراء من جانبك، ولكن يجب أن تكون على دراية بأن المستخدمين قد يظهر لهم مربع حوار التفويض في المرة الأولى التي يستخدمون فيها تطبيقك.

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

function onMessage(event) {
  var userProperties = PropertiesService.getUserProperties();
  if (!userProperties.getProperty('initialized')) {
    // handle the onAddToSpace initialization logic here.
    ...
    userProperties.setProperties({initialized: 'true'});
  }
  // Handle normal onMessage logic.
  ...
}

الرسائل غير المتزامنة

قد تحتاج بعض التطبيقات إلى إرسال رسائل إلى Google Chat استنادًا إلى عامل تشغيل خارجي، مثل مشغّل يستند إلى الوقت في "برمجة التطبيقات".

نخطط لدمج واجهة برمجة تطبيقات Google Chat في الأصل في "برمجة تطبيقات Google" لحالة الاستخدام هذه. وفي هذه الأثناء، تكون الطريقة الوحيدة لتحقيق ذلك حاليًا هي عبر واجهة برمجة تطبيقات HTTP الخارجية (راجع المستندات). يتطلب هذا استخدام حساب خدمة Cloud (اطلع على المستندات) من خلال مكتبة النصوص البرمجية OAuth2 للتطبيقات.

في ما يلي مثال على التطبيق الكامل الذي ينشر رسالة كل دقيقة على كل مساحة:

// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
//     https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.

// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
  PropertiesService.getScriptProperties()
      .setProperty(e.space.name, '');
  return {
    'text': 'Hi! I\'ll post a message here every minute. ' +
            'Please remove me after testing or I\'ll keep spamming you!'
  };
}

// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
  PropertiesService.getScriptProperties()
      .deleteProperty(e.space.name);
}

// Add a trigger that invokes this function every minute via the
// "Edit > Current Project's Triggers" menu. When it runs, it will
// post in each space the app was added to.
function onTrigger() {
  var spaceIds = PropertiesService.getScriptProperties()
      .getKeys();
  var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
  for (var i = 0; i < spaceIds.length; ++i) {
    postMessage(spaceIds[i], message);
  }
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

ملف البيان

في ما يلي مثال على ملف بيان برمجة التطبيقات الذي يجب أن يصاحب النص البرمجي.

إذا لم تبدأ مشروعك من نموذج Chat، عليك تعديل ملف البيان لإضافة الكائن "chat": {} إليه.

في ملف البيان، اضبط وقت التشغيل على Rhino: "runtimeVersion": "DEPRECATED_ES5". لا تسمح تطبيقات Chat بشكل كامل بوقت تشغيل V8 لبرمجة التطبيقات، لذلك في حال تحديد "runtimeVersion": "V8"، من الممكن أن يحدث خطأ في تطبيق Chat. على سبيل المثال، يمكن أن تتغيّر بنية استجابة JSON بطرق غير متوقعة في تطبيقات Chat التي تم إنشاؤها باستخدام وقت التشغيل V8.

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "chat": {
    "addToSpaceFallbackMessage": "Thank you for adding me!"
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "DEPRECATED_ES5"
}

من الممكن أن يضيف المستخدم تطبيقك إلى مساحة قبل السماح لتطبيقك. في هذه الحالة، يتعذر على تطبيقك الاستجابة لحدث الإضافة إلى الفضاء. ويمكنك إرسال رسالة ترحيب لعرضها في حال حدوث ذلك باستخدام الحقل addToSpaceFallbackMessage.

يُطلق على ملف البيان اسم appsscript.json ويشكّل جزءًا من مشروع برمجة التطبيقات. لعرض ملف البيان في محرر برمجة التطبيقات، حدد عرض > عرض ملف البيان.