الوصول المبرمَج إلى بيانات "إحصاءات Google" في "جداول بيانات Google"

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

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

مقدمة

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

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

نظرة عامة

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

عند إنشاء تطبيق باستخدام واجهة برمجة التطبيقات Google Analytics API و"برمجة تطبيقات Google"، اتّبِع الخطوات التالية بشكل عام:

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

لنتناول كل خطوة بالتفصيل.

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

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

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

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

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

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

العمل باستخدام واجهة برمجة تطبيقات Google Analytics

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

• استرجع الملف الشخصي الأول للمستخدم المصرح له.
• إرسال طلب إلى واجهة برمجة التطبيقات الأساسية لإعداد التقارير بشأن البيانات
• إدراج البيانات في جدول بيانات.

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

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.

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

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. يتم نقل كل من رقم تعريف الحساب وأرقام تعريف الموقع الإلكتروني كمَعلمات لهذه الطريقة. وفي حال توفّر الملفات الشخصية، سيتم عرض الملف الشخصي الأول.

ملاحظة: يجب تفعيل خدمة واجهة برمجة التطبيقات Google Analytics API لجميع طرق Analytics.* لكي تعمل بشكل سليم.

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

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

إرسال طلب إلى واجهة برمجة التطبيقات الأساسية لإعداد التقارير بشأن البيانات

بعد الحصول على رقم تعريف ملف شخصي، يمكنك استخدام واجهة برمجة التطبيقات الأساسية لإعداد التقارير لطلب البحث عن بيانات تقارير "إحصاءات 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 في جدول بيانات في البرنامج التعليمي لتخزين البيانات في جداول البيانات.

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

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

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

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

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

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

ملاحظة: ما عليك سوى منح النص البرمجي إذن الوصول إلى بيانات "إحصاءات 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"، وهما:

• قراءة البيانات من جداول البيانات: يتيح لك ذلك تحديد طلبات بحث واجهات برمجة التطبيقات في جدول بيانات بدلاً من JavaScript.
• إدراج رسوم بيانية من جداول البيانات في موقع مصمم في "مواقع Google" – يمكنك إنشاء لوحات بيانات في "مواقع Google" باستخدام بيانات "إحصاءات Google".
• القوائم المخصصة : لتسهّل على المستخدمين الآخرين في شركتك استخدام النصوص البرمجية التي تكتبها.