الوصول التلقائي إلى بيانات "إحصاءات Google" في "جداول بيانات Google"

ميهايلوفسكي، فريق Google Analytics API – آب (أغسطس) 2012

يشرح هذا الدليل التوجيهي طريقة الوصول إلى واجهة برمجة التطبيقات Management and Core Reporting API في "جداول بيانات Google" باستخدام لغة "برمجة تطبيقات Google".


مقدمة

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

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

نظرة عامة

سيوضّح لك هذا الدليل التوجيهي كيفية التسجيل في بيئة "برمجة تطبيقات Google" وضبطها لاستخدام واجهة برمجة التطبيقات Google Analytics API. بعد ضبط الإعدادات، سيرشدك البرنامج التعليمي إلى كيفية استرداد رقم تعريف الملف الشخصي للمستخدم المفوَّض باستخدام Management API. وبعد ذلك، يمكنك استخدام معرّف الملف الشخصي لإجراء طلب بحث عن واجهة برمجة التطبيقات الأساسية لإعداد التقارير لعرض أهم 250 كلمة رئيسية لبحث الأجهزة الجوّالة من Google. وأخيرًا، سيتم إدراج النتائج في جدول بيانات Google. بعد حصولك على البيانات، سيناقش البرنامج التعليمي أيضًا طريقة استرداد البيانات بشكل مبرمَج.

عند إنشاء تطبيق باستخدام واجهة برمجة التطبيقات في "إحصاءات Google" و"برمجة التطبيقات"، سيتم تنفيذ الخطوات التالية بشكل عام:

  • تفعيل واجهات برمجة تطبيقات "إحصاءات Google" في "جداول بيانات Google"
  • العمل باستخدام واجهات برمجة تطبيقات "إحصاءات Google"

لنستعرض كل خطوة بالتفصيل.

تفعيل واجهة برمجة تطبيقات "إحصاءات Google" في "برمجة التطبيقات"

لتفعيل الوصول إلى بيانات "إحصاءات Google" من داخل جداول بيانات Google، يُرجى اتّباع الخطوات التالية:

  1. أنشئ ملفًا في "جداول بيانات Google". امنحه اسمًا رائعًا.
  2. إنشاء لغة "برمجة تطبيقات Google" جديدة
    1. في القائمة، انتقِل إلى الإضافات > برمجة التطبيقات.
    2. في حال ظهور قائمة، انقر على مشروع فارغ.
    3. ضع اسمًا للمشروع. تأكد من أن اسمًا رائعًا.

بعد الحصول على نص برمجي جديد، عليك تفعيل خدمة "إحصاءات Google".

  1. في مُحرِّر النصوص البرمجية، اختَر الموارد > خدمات Google المتقدمة...
  2. في مربّع الحوار الذي يظهر، انقر على مفتاح التبديل تفعيل/إيقاف بجانب واجهة برمجة التطبيقات Google Analytics.
  3. في أسفل مربّع الحوار، انقر على رابط Google Developers Console.
  4. في وحدة التحكّم الجديدة، انقر مرّة أخرى على مفتاح التشغيل/الإيقاف بجانب Google Analytics API. (بعد التفعيل، سيتم الانتقال إلى أعلى الصفحة.)
  5. ارجع إلى محرر النص البرمجي وانقر على حسنًا في مربّع الحوار.

من المفترض أن ينبثق مربع حوار أصفر صغير يشير إلى أنّك أضفت خدمة Google APIs جديدة إلى النص البرمجي. أصبحت الآن جاهزًا لبدء كتابة أول نص برمجي.

العمل باستخدام واجهة برمجة التطبيقات في "إحصاءات Google"

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

  • استرجع الملف الشخصي الأول للمستخدم المصرح له.
  • إجراء طلب بحث في Core Reporting API عن البيانات.
  • إدراج البيانات في جدول بيانات.

أضف الدالة التالية إلى المشروع الفارغ.

function runDemo() {
  try {

    var firstProfile = getFirstProfile();
    var results = getReportDataForProfile(firstProfile);
    outputToSpreadsheet(results);

  } catch(error) {
    Browser.msgBox(error.message);
  }
}

في الرمز البرمجي أعلاه، يتم استخدام كتلة try...catch لمعالجة أي أخطاء في واجهة برمجة التطبيقات. وفي حال حدوث أي أخطاء، سيتمّ إيقاف تنفيذ البرنامج وسيظهر الخطأ في مربّع رسالة. في مجموعة try، يتم استخدام دالة لتنفيذ كل خطوة من الخطوات التي يمرّ بها النص البرمجي. لنضيف الآن الرمز البرمجي لكل دالة من هذه الدوال.

استرداد (الملف الشخصي) للمستخدم المفوَّض

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

Google Analytics Management API توفر إمكانية الوصول إلى جميع الحسابات ومواقع الويب وكيانات الملفات الشخصية (الملف الشخصي) التي تنتمي إلى المستخدم. تنتمي كل كيان من هذه الكيانات إلى تسلسل هرمي، ويمكنك اجتياز هذا العرض الهرمي آليًا لاسترداد رقم تعريف الملف الشخصي للمستخدم المفوَّض.

والدالة الثانية التي سنكتبها ستجتاز التسلسل الهرمي لـ Management API وتعرض الملف الشخصي الأول للمستخدم. انسخ الرمز التالي والصقه في مشروع برمجة التطبيقات:

function getFirstProfile() {
  var accounts = Analytics.Management.Accounts.list();
  if (accounts.getItems()) {
    var firstAccountId = accounts.getItems()[0].getId();

    var webProperties = Analytics.Management.Webproperties.list(firstAccountId);
    if (webProperties.getItems()) {

      var firstWebPropertyId = webProperties.getItems()[0].getId();
      var profiles = Analytics.Management.Profiles.list(firstAccountId, firstWebPropertyId);

      if (profiles.getItems()) {
        var firstProfile = profiles.getItems()[0];
        return firstProfile;

      } else {
        throw new Error('No views (profiles) found.');
      }
    } else {
      throw new Error('No webproperties found.');
    }
  } else {
    throw new Error('No accounts found.');
  }
}

في هذه الدالة، يتم أول طلب عن مجموعة الحسابات باستخدام الطريقة Analytics.Management.Accounts.list. إذا كان المستخدم المفوَّض لديه حسابات على "إحصاءات Google"، يتم استرداد رقم تعريف الحساب الأول. بعد ذلك، يتم إجراء طلب بحث عن مجموعة المواقع الإلكترونية عن طريق استدعاء الطريقة Analytics.Management.Webproperties.list وتمرير الطريقة التي تم استرداد رقم تعريف الحساب خلالها في الخطوة السابقة. في حال توفُّر مواقع إلكترونية، يتم أخيرًا طلب البحث عن مجموعة الملف الشخصي (الملف الشخصي) باستخدام طريقة Analytics.Management.Profiles.list. يتم نقل رقم تعريف الحساب ورقم تعريف الموقع الإلكتروني كمَعلمات إلى هذه الطريقة. في حال توفّر الملفات الشخصية، سيتم عرض الملف الشخصي الأول.

في حال حدوث خطأ في واجهة برمجة التطبيقات في أي وقت، أو إذا لم يتم العثور على نتائج في استجابة واجهة برمجة التطبيقات، سيتم عرض خطأ مع رسالة تصف أنّه لم يتم العثور على أي نتائج. سترصد مجموعة catch في دالة runDemo أعلاه هذا الخطأ وتطبع الرسالة إلى المستخدم.

وبعد عرض النص البرمجي، يمكنه الآن طلب بيانات إعداد التقارير.

إجراء طلب بحث في Core Reporting API عن البيانات.

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

أضِف الرمز التالي إلى مشروع "برمجة تطبيقات Google":

function getReportDataForProfile(firstProfile) {

  var profileId = firstProfile.getId();
  var tableId = 'ga:' + profileId;
  var startDate = getLastNdays(14);   // 2 weeks (a fortnight) ago.
  var endDate = getLastNdays(0);      // Today.

  var optArgs = {
    'dimensions': 'ga:keyword',              // Comma separated list of dimensions.
    'sort': '-ga:sessions,ga:keyword',       // Sort by sessions descending, then keyword.
    'segment': 'dynamic::ga:isMobile==Yes',  // Process only mobile traffic.
    'filters': 'ga:source==google',          // Display only google traffic.
    'start-index': '1',
    'max-results': '250'                     // Display the first 250 results.
  };

  // Make a request to the API.
  var results = Analytics.Data.Ga.get(
      tableId,                    // Table id (format ga:xxxxxx).
      startDate,                  // Start-date (format yyyy-MM-dd).
      endDate,                    // End-date (format yyyy-MM-dd).
      'ga:sessions,ga:pageviews', // Comma seperated list of metrics.
      optArgs);

  if (results.getRows()) {
    return results;

  } else {
    throw new Error('No views (profiles) found');
  }
}

function getLastNdays(nDaysAgo) {
  var today = new Date();
  var before = new Date();
  before.setDate(today.getDate() - nDaysAgo);
  return Utilities.formatDate(before, 'GMT', 'yyyy-MM-dd');
}

ينشئ الجزء الأول من الرمز طلبًا ضمن واجهة Core Reporting API باستخدام طريقة Analytics.Data.Ga.get. تقبل الطريقة مجموعة من المعلَمات التي تحدّد نوع التقرير المطلوب استرداده. يتألف كل طلب بحث في Core Reporting API من مجموعة من المَعلمات المطلوبة والاختيارية. يتم تمرير المعلَمات المطلوبة إلى الطريقة كمعلَمات بينما يتم تمرير المعلَمات الاختيارية ككائن.

يجب إدخال المَعلمة table ID ويتم تكوينها عن طريق دمج البادئة ga: مع رقم تعريف الملف الشخصي. ينشئ الرمز رقم تعريف الجدول باستخدام رقم تعريف الملف الشخصي (الملف الشخصي) الذي تم استرداده في الخطوة السابقة. ويكون تاريخ البدء وتاريخ الانتهاء مطلوبَين أيضًا، وحدِّد النطاق الزمني للبيانات المطلوب استردادها. يتم احتساب كلتا القيمتين استنادًا إلى تاريخ اليوم باستخدام دالة getLastNdays. أخيرًا، يتم تمرير جميع المعلَمات الاختيارية إلى الدالة باستخدام الكائن optArgs.

عند تشغيل طريقة Analytics.Data.Ga.get، يتم تقديم طلب إلى Core Reporting API. وفي حال حدوث خطأ، يتم اكتشافه في مجموعة try...catch المحدّدة في طريقة runDemo الخارجية. وإذا كان الطلب ناجحًا، سيتم عرض النتائج.

إدراج البيانات في جدول بيانات

الخطوة الأخيرة في النص البرمجي هي إخراج النتائج من Core Reporting API في "جداول بيانات Google". وتُستخدَم طريقة outputToSpreadsheet لتنفيذ هذا الإجراء. أضِف الرمز التالي إلى مشروعك:

function outputToSpreadsheet(results) {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().insertSheet();

  // Print the headers.
  var headerNames = [];
  for (var i = 0, header; header = results.getColumnHeaders()[i]; ++i) {
    headerNames.push(header.getName());
  }
  sheet.getRange(1, 1, 1, headerNames.length)
      .setValues([headerNames]);

  // Print the rows of data.
  sheet.getRange(2, 1, results.getRows().length, headerNames.length)
      .setValues(results.getRows());
}

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

تشغيل النص البرمجي

بمجرد إضافة كل التعليمات البرمجية إلى المشروع، يمكنك الآن تشغيلها.

  • في شريط أدوات محرّر النصوص البرمجية، في القائمة المنسدلة لدالة التحديد، اختر runDemo.
  • بعد ذلك، انقر على الزرّ play.

في المرة الأولى التي يتم فيها تشغيل هذا، سيظهر مربّع منبثق يطلب منك السماح لهذا النص البرمجي بالوصول إلى بيانات حسابك على "إحصاءات Google".

انقر على "تفويض".

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

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

التشغيل التلقائي للنص البرمجي

عند هذه المرحلة، يجب أن يتوفّر لديك نص برمجي يطلب في Google Analytics API. قد تحتاج الآن إلى برمجة هذا النص البرمجي لاسترداد البيانات الجديدة كل ليلة. تُسهِّل "برمجة التطبيقات" التشغيل الآلي للغاية من خلال ميزة triggers.

ولبرمجة هذا النص البرمجي، اتّبِع الخطوات التالية:

  • في شريط أدوات محرّر النصوص البرمجية، انقر على Resources -> All your triggers....
  • انقر على Add a new trigger سيظهر مربّع حوار المشغّلات.
  • ضبط المشغِّل لتنفيذ طريقة runDemo كل ليلة
    • يجب ضبط القائمة المنسدلة Run على: runDemo.
    • يجب ضبط القائمة المنسدلة Events على: Time-driven وDay timer وMidnight to 1am.

وبعد ضبط هذا النص البرمجي، سيتم تشغيله كل ليلة، ما يمنحك بيانات جديدة في الصباح.

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

الخاتمة

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

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

هناك برنامجان تعليميان رائعان قد يكونان مفيدين لمساعدتك في الاستفادة بشكل أكبر من Google Analytics API و"برمجة تطبيقات Google"، هما: