REST for the Traveling Salesman: Using Google Data on Salesforce.com

"لين ليابراتن"، برامج المطوّرين في Google
تشرين الثاني (نوفمبر) 2007

مقدمة

تستضيف Salesforce.com وGoogle تطبيقات شائعة من نوع "برامج كخدمة"، وتوفّر كلتا المؤسستين واجهات برمجة تطبيقات تتيح للمطوّرين الوصول إلى مخازن البيانات الكبيرة التي تشغّل هذه التطبيقات، وتصبح الأمور مثيرة للاهتمام عندما نجمع بين مجموعتَي واجهات برمجة التطبيقات. يستمر استخدام G Suite بشكل متزايد في المؤسسات، وقد أنشأت Salesforce.com منصة شاملة لإنشاء تطبيقات مخصّصة للأنشطة التجارية، لذا تتوفّر العديد من الفرص للمطوّرين (أنت!) لدمج إمكانات Google وSalesforce.com.

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

مرحبًا، Salesforce.com!

إذا كنت مبتدئًا في Salesforce.com مثلي، عليك البدء بالاشتراك في حساب مطوِّر على ADN، أي شبكة مطوِّري Apex. يمنحك حساب المطوّر حسابًا كاملاً على Salesforce.com، بالإضافة إلى إمكانية الوصول إلى ويكي Apex ومنتديات المناقشة.

بعد ذلك، عليك الحصول على Apex Toolkit for Eclipse. تتطلّب مجموعة الأدوات Java 1.5 وEclipse 3.2.2 أو إصدارًا أحدث. إذا كنت تعرف كيفية استخدام Eclipse، يمكنك العثور على موقع تحديث البرامج الخاص بحزمة الأدوات على http://www.adnsandbox.com/eclipsetoolkit/10.0/. إذا لم تكن على دراية بإضافات Eclipse، أو حدث خطأ ما أثناء عملية التثبيت، تتضمّن صفحة Apex على Wiki تعليمات تفصيلية حول التثبيت.

بعد تثبيت مجموعة الأدوات، يمكنك الوصول إلى محتوى المساعدة في Apex المدمج في نظام المساعدة في Eclipse. في Eclipse، انتقِل إلى Help | Help Contents | Apex Toolkit for Eclipse للاطّلاع على هذا المحتوى. أحد مراجع المساعدة هو برنامج تعليمي سريع البدء يوضّح لك كيفية إنشاء مشروع جديد وإضافة عناصر S-Controls وفئات ومشغّلات. إذا لم يسبق لك العمل باستخدام رمز Apex، عليك الاطّلاع على هذا البرنامج التعليمي وإنشاء مشروع Apex قبل المتابعة.

تصدير الأحداث إلى "تقويم Google"

أنشأ Ron Hess تطبيق Google Calendar Mash-up الذي يتيح لك تصدير الأحداث من Salesforce.com إلى "تقويم Google". كتب رون أيضًا مقالة تشرح طريقة عمل المقطوعة الموسيقية التي أعدّها. تطبيق "جداول بيانات Google" الذي سأوضّح لك كيفية إنشائه لاحقًا مستوحى من دمج "تقويم Google" الذي أجراه رون. شكرًا "رون".

إذا كنت مستخدمًا متمرّسًا في Salesforce.com، يمكنك على الأرجح دمج تطبيق "تقويم Google" الخاص بـ Ron واستخدامه بدون أي تعليمات. كنت بحاجة إلى بعض المساعدة في البداية، لذا إليك ما فعلته لتجربة تطبيق "رون".

  1. ثبِّت التطبيق:
    • انتقِل إلى صفحة دمج تقويم Google وانقر على الحصول عليه الآن.
    • أدخِل بيانات اعتماد شبكة ADN وانقر على متابعة.
    • اقرأ "الأحكام والشروط" وانقر على متابعة.
    • انقر على التالي في صفحة "فحص محتويات الحزمة".
    • اختَر مستوى أمان وانقر على التالي.
    • انقر على تثبيت.
  2. ضبط وكيل AJAX في Salesforce.com
    • في قائمة "إعدادات الإدارة"، انقر على عناصر تحكّم الأمان | إعدادات الموقع الإلكتروني البعيد.
    • انقر على موقع إلكتروني بعيد جديد.
    • أدخِل Google في حقل "اسم الموقع البعيد"، واستخدِم https://www.google.com في حقل "عنوان URL للموقع البعيد".
    • انقر على حفظ.
  3. أضِف الزر "الإضافة إلى Google" إلى صفحة تفاصيل الحدث:
    • في قائمة "إعداد التطبيق" (App Setup)، انقر على تخصيص (Customize) | الأنشطة (Activities) | تخطيطات صفحة الحدث (Event Page Layouts).
    • انقر على تعديل في صف "تنسيق الحدث".
    • انقر مرّتين على منطقة "أزرار صفحة التفاصيل".
    • ظلِّل "الإضافة إلى Google" وانقر على السهم المتّجه لليسار (>) لإضافة الزر.
    • انقر على موافق.
    • انقر على حفظ في صفحة "خصائص تخطيط الصفحة".
  4. تصدير حدث
    • انقر على الصفحة الرئيسية في أعلى يمين الصفحة لعرض التقويم.
    • إذا لم يكن لديك أي أحداث، انقر على حدث جديد لإنشاء حدث.
    • انقر على حدث لعرض صفحة "تفاصيل الحدث".
    • انقر على الزر الإضافة إلى Google.
    • انقر على حسنًا من خلال تنبيه JavaScript
    • سجِّل الدخول باستخدام اسم المستخدم وكلمة المرور لحسابك على Google.
    • انقر على منح إذن الوصول لمنح تطبيق SalesForce إذن الكتابة في "تقويم Google".
    • عرض الحدث في تقويم Google

إنشاء تطبيق "جداول بيانات Google"

حسنًا، من المحتمل أنّك مللت من النقر على صفحات Salesforce.com وأصبحت مستعدًا لكتابة بعض الرموز. أعِد تشغيل Eclipse وستلاحظ أنّ مشروع Apex الذي أنشأته يحتوي الآن على عناصر S-Controls لتطبيق "تقويم Google" الخاص بـ Ron. ويرجع ذلك إلى أنّ Apex Toolkit for Eclipse تتم مزامنته باستمرار مع Salesforce.com، أليس هذا رائعًا؟

يمكنك إنشاء تطبيق "بيانات Google" الخاص بك من خلال إعادة استخدام بعض وظائف "تطبيق Google Calendar Mash-up"، مثل عناصر التحكّم في المصادقة. في بقية هذا القسم، سأوضّح لك كيفية إنشاء تطبيق يصدّر جهات اتصالك على Salesforce.com إلى جدول بيانات Google.

نشر عنصر تحكّم بسيط من نوع S-Control

عنصر تحكّم S-Control هو ملف تستضيفه Salesforce.com ويتم تنفيذه في متصفحات الويب عندما يصل المستخدمون إلى تطبيقك. يمكن أن يحتوي عنصر تحكّم S-Control على أي نوع من المحتوى الذي يمكنك عرضه أو تشغيله في متصفّح ويب، مثل HTML أو CSS أو JavaScript.

هناك الكثير من الأجزاء المتحركة في عملية دمج Salesforce.com وGoogle، لذا كان أول ما فعلته هو إضافة زر "تصدير إلى Google" إلى صفحة قائمة جهات الاتصال التي تستدعي عنصر تحكّم بسيطًا في S-Control، وذلك للتأكّد من أنّ كل الأجزاء تعمل بشكل صحيح قبل أن أتعمّق في JavaScript.

في مشروع Apex، انقر بزر الماوس الأيمن على مجلد "عناصر تحكّم S" (S-Controls) واختَر Apex | عنصر تحكّم S جديد. امنح عنصر التحكّم S-Control الجديد تصنيفًا واسمًا export_contacts، واترك النوع HTML مخصّصة وانقر على إنهاء.

سيحتوي عنصر S-Control الجديد على ملف HTML أساسي. ستضيف مجموعة من JavaScript في <head>، ولكن يمكنك ملء <body> أولاً، حتى يكون هناك شيء يظهر للمستخدم أثناء تصدير جهات الاتصال. انسخ رمز HTML هذا إلى نص S-Control لعرض "نقاط الانتظار" وشعار "جداول بيانات Google":

<div id="waiting" align="center" />
  <img src="/img/icon/home32.png" height="64" width="64" />
  <img src="/img/waiting_dots.gif" alt="Please wait..." title="Please wait..." height="25" width="196" />
  <img src="http://docs.google.com/images/doclist/logo_docs.gif" />
  <p><h3>Exporting contacts to Google Spreadsheets, please wait...</h3></p>

</div>

يمكنك الآن نشر عنصر S-Control وإعداد زر سيؤدي إلى تشغيله.

  1. استخدِم Eclipse لنشر ملف S-Control:
    • انقر بزر الماوس الأيمن على مشروع Apex واختَر Apex | المزامنة مع Salesforce.
    • ابحث عن عنصر S-Control الجديد في شجرة الدليل، وانقر عليه بزر الماوس الأيمن واختَر تجاوز العنصر البعيد ونشره على الخادم.
    • إذا لم تتمكّن من العثور على S-Control، من المحتمل أنّ Apex Toolkit قد حمّلتها لك من قبل، ولكن من المستحسن استخدام طريقة العرض المتزامنة للتأكّد من أنّ أحدث رمز يتم تنفيذه على الخادم.
  2. استخدِم واجهة مستخدم Salesforce.com لتحديد زرّ سيؤدي إلى استدعاء عنصر S-Control هذا:
    • في قائمة "إعداد التطبيق"، انقر على تخصيص | جهات الاتصال | الأزرار والروابط.
    • في قسم "الأزرار والروابط المخصّصة"، انقر على جديد.
    • أدخِل التصدير إلى Google في الحقل "التصنيف"، واحتفِظ بالاسم Export_to_Google.
    • اختَر "زر القائمة" كنوع العرض.
    • اختَر "عنصر تحكّم S-Control مخصّص" كمصدر المحتوى.
    • اختَر "العرض في نافذة حالية مع الشريط الجانبي" كـ "السلوك".
    • اختَر "تصدير جهات الاتصال" من قائمة عناصر التحكّم S المخصّصة.
  3. أضِف الزر إلى قائمة جهات الاتصال:
    • في قائمة "إعداد التطبيق"، انقر على تخصيص | جهات الاتصال | تخطيطات البحث.
    • انقر على تعديل في صف "عرض قائمة جهات الاتصال".
    • ميِّز "التصدير إلى Google" وانقر على السهم المتّجه لليسار (<) لإضافة الزر.
    • انقر على حفظ.
  4. جرِّبها:
    • انقر على علامة التبويب جهات الاتصال.
    • اختَر "كل جهات الاتصال" كطريقة العرض وانقر على انتقال.
    • انقر على الزر الجديد التصدير إلى Google.
    • شاهِد "نقاط الانتظار" ولكن لا تتوقّع حدوث أي شيء آخر.

التفاعل مع "جداول بيانات Google"

إذا نظرت إلى مصدر Google Calendar Mash-up، ستلاحظ أنّ الملف gcal_snippet.scf يحتوي على تجريد لخادم "تقويم Google". للتفاعل مع "جداول بيانات Google"، عليك إنشاء ملف مشابه لخادم "جداول بيانات Google". أعدتُ استخدام رمز Ron Hess الخاص باستخدام خادم وكيل AJAX في Salesforce.com والمصادقة باستخدام Google AuthSub، واستبدلتُ الدالة التي تكتب الأحداث في "تقويم Google" بدالة تكتب المعلومات في "جداول بيانات Google". يتوفّر المصدر الكامل لهذا الملف في gspreadsheet_snippet.scf.

بعد ذلك، أضفتُ JavaScript إلى export_contacts.scf S-Control لطلب معلومات الاتصال من Salesforce.com وكتابتها في جدول بيانات Google. يمكنك بسهولة استخراج البيانات من Salesforce.com. ما عليك سوى إنشاء طلب بحث وتوفير دالة رد اتصال لتنفيذها عند عرض البيانات. على سبيل المثال:

  var query = 'Select FirstName, LastName, Phone From Contact';
  var queryResult = sforce.connection.query(query, queryCallback);

بعد الحصول على معلومات الاتصال من Salesforce.com، عليك تحديد المكان الذي تريد تصديرها إليه. في بروتوكول Google Data المتوافق مع REST، يمكن تحديد كل جدول بيانات من خلال عنوان URL فريد. يمكنك الحصول على قائمة بجداول بيانات المستخدم (وعناوين URL المرتبطة بها) من خلال طلب البحث عن عنوان URL الخاص بالخلاصة الوصفية: http://spreadsheets.google.com/feeds/spreadsheets/private/full. تكرّر الطريقة التالية هذه الجداول، بحثًا عن جدول بيانات بعنوان محدّد. عندما يعثر على جدول البيانات الصحيح، يحصل أولاً على قائمة بأوراق العمل، ثم يعرض عنوان URL لخلاصة الخلايا الخاصة بورقة العمل الأولى.

function getCellFeedUrl() {
  var SPREADSHEET_TITLE = 'Salesforce.com Contacts';
  var WORKSHEET_REL = 'http://schemas.google.com/spreadsheets/2006#worksheetsfeed';
  var CELLSFEED_REL = 'http://schemas.google.com/spreadsheets/2006#cellsfeed';

  // Query to find the spreadheet called "Salesforce.com Contacts"
  var spreadsheets = g.getFeed('http://spreadsheets.google.com/feeds/spreadsheets/private/full');
  var entries = g.getEntryList(spreadsheets);
  for (var e in entries) {
    if (g.getTitle(entries[e]) == SPREADSHEET_TITLE) {
      var worksheetsFeedUrl = g.link(entries[e],WORKSHEET_REL);
      var worksheets = g.getFeed(worksheetsFeedUrl);
      var worksheetEntries = g.getEntryList(worksheets);
      return g.link(worksheetEntries[0], CELLSFEED_REL);
    }
  }
}

يمكنك العثور على مزيد من المعلومات حول الخلاصات المتوفرة في واجهة برمجة التطبيقات الخاصة ببيانات "جداول بيانات Google" في دليل المراجع.

تستخدم الدالة queryCallback الطريقة getCellFeedUrl للعثور على عنوان URL لخلايا الخلاصة اللازم لإرسال طلبات تعديل الخلايا، ثم تكتب معلومات الاتصال في خلية واحدة في كل مرة.

function queryCallback(queryResult) {
  var cellFeedUrl = getCellFeedUrl();
  var contacts = queryResult.getArray('records');
  for (var i=0; i<contacts.length; i++) {
    g.updateCell(cellFeedUrl, i+1, 1, contacts[i].LastName + ", " + contacts[i].FirstName);
    g.updateCell(cellFeedUrl, i+1, 2, contacts[i].Phone);
  }
  
  jumpback(); // Return to the contacts page when your done
}

تتوفّر الطريقة updateCell في عنصر S-Control gspreadsheet_snippet.scf. تحصل الطريقة على عنوان URL للتعديل الخاص بالخلية في الصف والعمود المحدّدين، ثم ترسل رسالة HTTP PUT تحتوي على تمثيل بيانات Google للخلية المعدَّلة:

GoogleSpreadsheet.prototype.updateCell = function(cellsFeedUrl, row, column, content ) {
  var cellEntry = this.getFeed(cellsFeedUrl+'/R'+row+'C'+column);
  var cellEditUrl = this.link(cellEntry,'edit');

  var newCellEntry = "<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'>" +
      "<atom:category scheme='http://schemas.google.com/spreadsheets/2006' " +
      "term='http://schemas.google.com/spreadsheets/2006#cell' />" +
      "<gs:cell xmlns:gs='http://schemas.google.com/spreadsheets/2006' " +
      "row='" + row + "' col='" + column + "' inputValue='" + content + "' />" +
      "</atom:entry>";

  this.putEntry(cellEditUrl, newCellEntry);
}

يمكنك الاطّلاع على مزيد من المعلومات حول كيفية تعديل الخلايا باستخدام Google Spreadsheets Data API في دليل المطوّرين.

تستخدم واجهة برمجة التطبيقات الخاصة ببيانات "جداول بيانات Google" النطاق الفرعي https://spreadsheets.google.com، لذا قبل أن يعمل الرمز أعلاه، عليك ضبط خادم وكيل AJAX في Salesforce.com وإضافة https://spreadsheets.google.com.

عليك أيضًا الانتقال إلى مستندات Google وإنشاء جدول بيانات جديد لتخزين البيانات. تأكَّد من حفظه باسم جهات اتصال Salesforce.com.

بعد تحميل عناصر S-Controls هذه، ستتمكّن من تصدير معلومات الاتصال إلى جدول بيانات Google. ماذا عن الطريقة الأخرى؟ باستخدام معرفتك الجديدة بمنصة Salesforce.com وواجهات برمجة تطبيقات بيانات Google، يمكنك أيضًا كتابة بعض الرموز البرمجية لاستيراد معلومات الاتصال من "جداول بيانات Google" إلى Salesforce.com.

الخاتمة

لم تتناول هذه المقالة سوى جزء بسيط من الموضوع، ولكن بعد أن أصبحت على دراية بمنصة Salesforce.com وواجهات برمجة التطبيقات الخاصة ببيانات Google، يمكنك التفكير في جميع التطبيقات التي يمكنك كتابتها للاستفادة من هذه الأنظمة الفعّالة. تتوسّع مجموعة واجهات برمجة التطبيقات Google Data باستمرار، ما يتيح لك الاستفادة من المزيد من المعلومات في تطبيقاتك، وتوفّر منصة Salesforce.com العديد من الأدوات المفيدة التي لم يتم تناولها في هذه المقالة. سأبحث عن تطبيقك المدمج التالي في AppExchange.

نتمنّى لك التوفيق في الترميز.

الموارد