دسترسی خودکار به داده های Google Analytics در Google Sheets

Nick Mihailovski، تیم Google Analytics API – آگوست 2012

این آموزش نحوه دسترسی به APIهای مدیریت و گزارش اصلی در Google Sheets را با استفاده از Apps Script توضیح می‌دهد.

معرفی

می‌توانید از Google Analytics API و Google Apps Script برای دسترسی به داده‌های Google Analytics خود از Google Sheets استفاده کنید. این قدرتمند است زیرا به شما امکان می دهد از تمام ویژگی های عالی Google Sheets با داده های تجزیه و تحلیل خود مانند اشتراک گذاری آسان، همکاری، نمودار و ابزارهای تجسم استفاده کنید.

این آموزش شما را از طریق کدهای مورد نیاز برای دسترسی به داده های Google Analytics در Google Sheets با استفاده از Google Apps Script راهنمایی می کند.

بررسی اجمالی

این آموزش نحوه ثبت نام و پیکربندی محیط Apps Script را برای استفاده از Google Analytics API نشان می دهد. پس از پیکربندی، آموزش نحوه بازیابی شناسه نمای (نمایه) برای کاربر مجاز با استفاده از مدیریت API را راهنمایی می کند. سپس نحوه استفاده از شناسه view (نمایه) برای پرس و جو از Core Reporting API برای بازیابی ۲۵۰ کلمه کلیدی برتر جستجوی موبایل از گوگل. در نهایت نتایج در یک صفحه گسترده گوگل درج می شود. هنگامی که داده دارید، این آموزش همچنین نحوه بازیابی خودکار داده ها را مورد بحث قرار می دهد.

هنگامی که برنامه ای را با استفاده از Google Analytics API و Apps Script می سازید، به طور کلی مراحل زیر را طی می کنید:

• API های Google Analytics را در Google Sheets فعال کنید
• با API های Google Analytics کار کنید

بیایید هر مرحله را با جزئیات مرور کنیم.

Google Analytics API را در Apps Script فعال کنید

برای فعال کردن دسترسی به داده های Google Analytics خود از داخل Google Sheets، این مراحل را دنبال کنید:

1. یک فایل Google Sheets ایجاد کنید. یه اسم باحال بذار
2. یک Apps Script جدید ایجاد کنید.
   1. در منو، به Extensions > Apps Script بروید.
   2. اگر منویی ظاهر شد، فقط روی Blank Project کلیک کنید.
   3. پروژه را نام ببرید. مطمئن شوید که نام جالبی دارد.

هنگامی که یک اسکریپت جدید دارید، باید سرویس Google Analytics را فعال کنید .

1. در ویرایشگر اسکریپت، Resources > Advanced Google services را انتخاب کنید...
2. در گفتگوی ظاهر شده، روی کلید روشن/خاموش در کنار Google Analytics API کلیک کنید.
3. در پایین کادر گفتگو، روی پیوند Google Developers Console کلیک کنید.
4. در کنسول جدید، دوباره روی کلید روشن/خاموش در کنار Google Analytics API کلیک کنید. (پس از فعال شدن، به بالای صفحه می‌رود.)
5. به ویرایشگر اسکریپت برگردید و در گفتگو روی OK کلیک کنید.

یک کادر گفتگوی زرد کوچک باید ظاهر شود که می گوید شما با موفقیت یک سرویس Google APIs جدید را به اسکریپت خود اضافه کرده اید. اکنون آماده شروع نوشتن اولین فیلمنامه خود هستید.

با Google Analytics API کار کنید

این اسکریپت در این آموزش، API Google Analytics را برای 250 کلمه کلیدی برتر جستجوی موبایل گوگل جستجو می کند، سپس نتایج را در Google Sheets خروجی می دهد. برای انجام این کار، اسکریپت مراحل زیر را طی می کند:

• اولین نمای (نمایه) کاربر مجاز را بازیابی کنید.
• برای داده ها از Core Reporting API پرس و جو کنید.
• درج داده ها در یک صفحه گسترده

تابع زیر را به پروژه خالی اضافه کنید.

function runDemo() {
  try {

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

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

در کد بالا، یک بلوک try...catch برای رسیدگی به هر گونه خطای API استفاده می شود. در صورت بروز هر گونه خطایی، اجرای برنامه متوقف می شود و خطا در کادر پیام نمایش داده می شود. در بلوک try ، یک تابع برای انجام هر یک از مراحلی که اسکریپت طی خواهد کرد استفاده می شود. حالا بیایید کد هر یک از این توابع را اضافه کنیم.

بازیابی اولین نمای کاربر مجاز (نمایه)

در گوگل آنالیتیکس، هر گزارش متعلق به یک view (پروفایل) است و با شناسه view (پروفایل) مشخص می شود. بنابراین هنگامی که یک پرس و جو برای داده های گزارش تعیین می کنید، باید شناسه نمای (نمایه) نمای (پروفایل) را نیز که می خواهید داده ها را از آن بازیابی کنید، مشخص کنید.

Google Analytics Management API دسترسی به تمام حساب‌ها، ویژگی‌های وب و موجودیت‌های مشاهده (نمایه) را که به یک کاربر تعلق دارند، فراهم می‌کند. هر یک از این موجودات به یک سلسله مراتب تعلق دارند و شما می توانید به صورت برنامه نویسی از این سلسله مراتب عبور کنید تا شناسه view (پروفایل) را برای کاربر مجاز بازیابی کنید.

توجه : در سند نمای کلی مدیریت API درباره نحوه ارتباط این موجودیت ها با یکدیگر بیشتر بیاموزید.

تابع دومی که خواهیم نوشت، سلسله مراتب مدیریت API را به پایین طی می کند و اولین نمای کاربر (نمایه) را برمی گرداند. کد زیر را کپی کرده و در پروژه Apps Script خود جایگذاری کنید:

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.');
  }
}

در این تابع ابتدا مجموعه Accounts با استفاده از روش Analytics.Management.Accounts.list پرس و جو می شود. اگر کاربر مجاز دارای حساب های Google Analytics باشد، شناسه حساب اول بازیابی می شود. در مرحله بعد، با فراخوانی متد Analytics.Management.Webproperties.list و ارسال روشی که شناسه حساب در مرحله قبل بازیابی شده بود، مجموعه ویژگی های وب مورد پرسش قرار می گیرد. اگر ویژگی های وب وجود داشته باشد، مجموعه view (نمایه) در نهایت با استفاده از روش Analytics.Management.Profiles.list پرس و جو می شود. هر دو شناسه حساب و شناسه دارایی وب به عنوان پارامتر به این روش ارسال می شوند. اگر نماها (پروفایل) وجود داشته باشد، اولین نمای (نمایه) برگردانده می شود.

توجه : سرویس Google Analytics API باید فعال باشد تا همه روش‌های Analytics.* به درستی کار کنند.

اگر در هر زمانی یک خطای API رخ دهد، یا اگر پاسخ API حاوی هیچ نتیجه‌ای نباشد، یک خطا با پیامی نشان می‌دهد که هیچ نتیجه‌ای پیدا نشده است. بلوک catch در تابع runDemo بالا این خطا را دریافت کرده و پیام را برای کاربر چاپ می کند.

پس از بازگشت اسکریپت، اکنون می تواند برای گزارش داده ها پرس و جو کند.

برای داده ها از Core Reporting API پرس و جو کنید.

هنگامی که یک شناسه view (پروفایل) دارید، از Core Reporting API برای پرس و جو برای داده های گزارش Google Analytics استفاده می کنید. در این بخش یاد می گیرید که چگونه این API را با استفاده از Apps Script پرس و جو کنید.

کد زیر را به پروژه Apps Script خود اضافه کنید:

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: به شناسه view (پروفایل) تشکیل می شود. کد با استفاده از شناسه view (پروفایل) بازیابی شده در مرحله قبل، شناسه جدول را ایجاد می کند. تاریخ شروع و پایان نیز مورد نیاز است و محدوده تاریخ داده ها را برای بازیابی مشخص می کند. هر دو بر اساس تاریخ امروز با استفاده از تابع getLastNdays محاسبه می شوند. در نهایت تمام پارامترهای اختیاری با استفاده از شی optArgs به تابع ارسال می شوند.

توجه : فهرست کاملی از تمام پارامترها و تعاریف آنها را می توان در سند مرجع Core Reporting API یافت. همچنین فهرست کاملی از تمام ابعاد و معیارهای ممکن را می توان در مرجع ابعاد و متریک ها یافت.

هنگامی که متد Analytics.Data.Ga.get اجرا می شود، درخواستی به Core Reporting API ارسال می شود. اگر خطایی رخ دهد، در بلوک try...catch تعریف شده در روش outer runDemo گرفته می شود. در صورت موفقیت آمیز بودن درخواست، نتایج برگردانده می شوند.

درج داده ها در یک صفحه گسترده

مرحله نهایی در اسکریپت ما خروجی نتایج از Core Reporting API در Google Sheets است. متد 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، نوشتن داده‌ها از اشیاء جاوا اسکریپت به صفحه‌گسترده را در آموزش ذخیره داده‌ها در صفحات گسترده بخوانید.

اسکریپت را اجرا کنید

پس از اینکه تمام کدها را به پروژه اضافه کردید، اکنون می توانید آن را اجرا کنید.

• در نوار ابزار ویرایشگر اسکریپت، در منوی کشویی تابع select، runDemo انتخاب کنید.
• بعد، روی دکمه play کلیک کنید.

اولین باری که این را اجرا می‌کنید، یک کادر پاپ‌آپ ظاهر می‌شود که از شما می‌خواهد این اسکریپت را برای دسترسی به داده‌های حساب Google Analytics خود مجاز کنید.

مجوز را کلیک کنید.

پس از کلیک کردن، صفحه جدیدی که در google.com میزبانی شده است باز می شود و از شما می خواهد به این اسکریپت اجازه دسترسی به داده های خود بدهید. پس از کلیک بر روی اجازه، به صفحه تایید هدایت می شوید. در این مرحله، اسکریپت اکنون می‌توانید به داده‌های Google Analytics خود دسترسی داشته باشید و می‌توانید به اجرای آن ادامه دهید.

توجه : شما فقط باید به اسکریپت اجازه دسترسی به داده های Google Analytics خود را در اولین باری که اسکریپت اجرا می شود بدهید.

پس از اجرای اسکریپت، روی پنجره با Google Sheets کلیک کنید. شما باید تمام داده های کلمات کلیدی را که از API بازگردانده شده اند، یا یک جعبه پیام با یک پیام خطا را ببینید.

خودکار کردن اسکریپت

در این مرحله باید اسکریپتی داشته باشید که API گوگل آنالیتیکس را پرس و جو کند. اکنون ممکن است بخواهید این اسکریپت را خودکار کنید تا هر شب داده های جدید را بازیابی کنید. Apps Script با استفاده از ویژگی triggers ، اتوماسیون را بسیار آسان می کند.

برای خودکار کردن این اسکریپت مراحل زیر را طی کنید:

• در نوار ابزار ویرایشگر اسکریپت، روی Resources -> All your triggers...
• روی Add a new trigger کلیک کنید. کادر گفتگوی تریگرها ظاهر می شود.
• ماشه را طوری پیکربندی کنید که هر شب متد runDemo را اجرا کند
  • منوی کشویی Run باید روی runDemo تنظیم شود
  • منوی کشویی Events باید روی این موارد تنظیم شود: Time-driven ، Day timer ، و Midnight to 1am .
  
  

  

پس از پیکربندی، این اسکریپت هر شب اجرا می‌شود و صبح اطلاعات تازه‌ای به شما می‌دهد.

اگر هر گونه خطایی در شب رخ دهد، باید به شما اطلاع داده شود. Apps Script همچنین به شما این امکان را می دهد که در صورت بروز هر گونه خرابی، یک هشدار ایمیل ارسال کنید. برای پیکربندی این، در کادر گفتگوی محرک‌ها، روی پیوند notifications کلیک کنید. یک کادر محاوره ای جدید باز می شود و به شما امکان می دهد خطاها را به کدام ایمیل ارسال کنید.

نتیجه

شما با موفقیت ثبت نام کرده اید و اجازه دسترسی به اسکریپت خود را داده اید. شما چندین بار از مدیریت API برای بازیابی شناسه نما (نمایه) سؤال کرده اید. سپس از شناسه view (پروفایل) برای پرس و جو از Core Reporting API برای بازیابی داده ها و خروجی آن در Google Sheets استفاده کردید.

استفاده از تکنیک های توضیح داده شده در آموزش به شما امکان می دهد تحلیل های پیچیده تری انجام دهید، بینش بیشتری به دست آورید، داشبوردهای سفارشی بسازید و زمان زیادی را برای اجرای گزارش های دستی کاهش دهید.

چند آموزش جالب دیگر که ممکن است برای کمک به استفاده بیشتر از Google Analytics API و Google Apps Script مفید باشد:

• خواندن داده ها از صفحات گسترده – بنابراین می توانید پرس و جوهای API خود را به جای جاوا اسکریپت در یک صفحه گسترده مشخص کنید.
• درج نمودارها از صفحات گسترده در یک سایت Google – بنابراین می توانید داشبوردهایی را در سایت های گوگل با داده های آنالیتیکس خود ایجاد کنید.
• منوهای سفارشی – برای سهولت استفاده سایر کاربران در شرکت شما از اسکریپت هایی که می نویسید.