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

"نيك ميلوفسكي"، فريق"إحصاءات Google"لواجهة برمجة التطبيقات – آب (أغسطس) 2012

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

المقدمة

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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

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

ملاحظة: اطّلِع على مزيد من المعلومات حول كيفية ارتباط هذه الكيانات ببعضها البعض في المستند نظرة عامة على واجهة برمجة التطبيقات للإدارة.

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

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

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

إجراء طلب بحث عن البيانات الأساسية من Reporting API

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

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

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

ملاحظة: يمكن العثور على قائمة كاملة بجميع المعلَمات وتعريفاتها في مستند مرجع واجهة برمجة التطبيقات لإعداد التقارير الأساسية. يمكنك أيضًا الاطّلاع على قائمة كاملة بكل الأبعاد والمقاييس المحتملة في مرجع السمات والمقاييس.

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

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

الخطوة الأخيرة في نصنا البرمجي هي عرض النتائج من واجهة برمجة التطبيقات الأساسية لإعداد التقارير في "جداول بيانات 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". يمكنك الآن تشغيل هذا النص البرمجي بشكل تلقائي لاسترداد البيانات الجديدة كل ليلة. تعمل"برمجة التطبيقات"على تسهيل التشغيل المبرمَج باستخدام ميزة triggers.

لتنفيذ هذا النص البرمجي تلقائيًا، يُرجى اتباع الخطوات التالية:

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

  

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

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

الخاتمة

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

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

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

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