این سند نحوه استفاده از Core Reporting API برای دسترسی به داده های Google Analytics را توضیح می دهد.
معرفی
Core Reporting API دسترسی به داده های جدولی در گزارش های استاندارد و سفارشی Google Analytics را فراهم می کند. برای دسترسی به داده ها، یک پرس و جو ایجاد می کنید که مشخص می کند: نمای (نمایه)، تاریخ شروع و پایان، و ابعاد و معیارهایی که سرصفحه های ستون را در جدول تشکیل می دهند. این پرس و جو به Core Reporting API ارسال می شود و Core Reporting API تمام داده ها را در قالب یک جدول برمی گرداند.
اگر با API تازه کار هستید، برای آشنایی با هدف Core Reporting API و دادههایی که ارائه میکند ، Core Reporting API Overview را بخوانید.
قبل از اینکه شروع کنی
این راهنما نحوه دسترسی به API Google Analytics را با استفاده از زبان های برنامه نویسی جاوا، پایتون، PHP و جاوا اسکریپت نشان می دهد.
- صفحه کتابخانه های سرویس گیرنده را برای لیست کاملی از کتابخانه های مشتری خاص زبان برنامه نویسی که با API کار می کنند، بخوانید.
- برای دسترسی به API بدون کتابخانه مشتری ، راهنمای مرجع را بخوانید.
هر کتابخانه مشتری یک شیء سرویس تجزیه و تحلیل واحد را برای دسترسی به تمام دادههای Core Reporting API ارائه میکند. برای ایجاد شیء سرویس معمولاً باید مراحل زیر را طی کنید:
- برنامه خود را در Google API Console ثبت کنید.
- اجازه دسترسی به داده های Google Analytics را بدهید.
- یک شیء سرویس Analytics ایجاد کنید.
اگر این مراحل را کامل نکردهاید، لطفاً توقف کرده و آموزش API Hello Google Analytics را بخوانید. این آموزش شما را در مراحل اولیه ساخت اپلیکیشن Google Analytics API راهنمایی می کند. پس از تکمیل، می توانید از این راهنما برای انجام کارهای دنیای واقعی استفاده کنید.
قطعه کد زیر حاوی متغیری برای ذخیره یک شیء سرویس مجاز است.
جاوا
Analytics analytics = // Read Hello Analytics Tutorial for details.
پایتون
analytics = # Read Hello Analytics Tutorial for details.
PHP
$client = // Read Hello Analytics Tutorial for details. // Return results as objects. $client->setUseObjects(true); $analytics = new apiAnalyticsService($client);
کتابخانه PHP تمام نتایج API را به عنوان یک آرایه انجمنی برمی گرداند. برای برگرداندن اشیاء واقعی به جای آن، می توانید روش مشتری useObject
را همانطور که در مثال بالا نشان داده شده است فراخوانی کنید.
جاوا اسکریپت
<script src="https://apis.google.com/js/client.js?onload=loadLib"</script> <script> function loadLib() { // Handle all the authorization work. // Read Hello Analytics Tutorial for details. gapi.client.load('analytics', 'v3', makeApiCall); } </script>
اولین تگ اسکریپت کتابخانه جاوا اسکریپت Google API را بارگیری می کند. پس از بارگیری، loadLib
برای بارگیری کلاس سرویس تجزیه و تحلیل اجرا می شود. پس از تکمیل، شی gapi.client.analytics
باید در DOM وجود داشته باشد و آماده استفاده برای جستجو در Core Reporting API باشد.
هنگامی که یک شی سرویس تجزیه و تحلیل ایجاد می کنید، آماده درخواست به Core Reporting API هستید.
توجه : شیء سرویس تجزیه و تحلیل همچنین می تواند برای دسترسی به مدیریت API استفاده شود.
بررسی اجمالی
برنامهای که از Core Reporting API استفاده میکند معمولاً ۲ مرحله را دنبال میکند:
- Core Reporting API را پرس و جو کنید
- با نتایج API کار کنید
بیایید به هر دو مرحله نگاه کنیم.
Core Reporting API را پرس و جو کنید
یک پرس و جو Core Reporting API بسازید
شیء سرویس تجزیه و تحلیل شامل روشی برای ساخت یک پرس و جوی Core Reporting API است.
هر پرس و جو Core Reporting API شامل مجموعه ای از پارامترها است که مشخص می کند چه داده هایی را باید برگرداند. یکی از مهمترین پارامترهای پرس و جو، پارامتر ids
یا شناسه جدول است. این پارامتر مشخص می کند که گوگل آنالیتیکس از کدام نمای (نمایه) داده ها را بازیابی کند. مقدار در قالب ga:xxx
است که xxx
شناسه نمای (نمایه) است.
جاوا
Get apiQuery = analytics.data().ga() .get(tableId, // Table Id. "2012-01-01", // Start date. "2012-01-15", // End date. "ga:sessions") // Metrics. .setDimensions("ga:source,ga:keyword") .setSort("-ga:sessions,ga:source") .setFilters("ga:medium==organic") .setMaxResults(25);
پایتون
api_query = service.data().ga().get( ids=TABLE_ID, start_date='2012-01-01', end_date='2012-01-15', metrics='ga:sessions', dimensions='ga:source,ga:keyword', sort='-ga:sessions,ga:source', filters='ga:medium==organic', max_results='25')
PHP
private function queryCoreReportingApi() { $optParams = array( 'dimensions' => 'ga:source,ga:keyword', 'sort' => '-ga:sessions,ga:source', 'filters' => 'ga:medium==organic', 'max-results' => '25'); return $service->data_ga->get( TABLE_ID, '2010-01-01', '2010-01-15', 'ga:sessions', $optParams); }
در این کتابخانه، متد get
نه تنها یک پرس و جو Core Reporting API ایجاد می کند، بلکه درخواست را به API نیز اجرا می کند.
جاوا اسکریپت
function makeApiCall() { var apiQuery = gapi.client.analytics.data.ga.get({ 'ids': TABLE_ID, 'start-date': '2010-01-01', 'end-date': '2010-01-15', 'metrics': 'ga:sessions', 'dimensions': 'ga:source,ga:keyword', 'sort': '-ga:sessions,ga:source', 'filters': 'ga:medium==organic', 'max-results': 25 }); // ... }
در این مثال، تابع makeApiCall
پس از بارگیری کتابخانه سرویس گیرنده جاوا اسکریپت فراخوانی می شود. در داخل، تابع یک پرس و جو API جدید Google Analytics ایجاد می کند و شی را در متغیر apiQuery
ذخیره می کند.
فهرست کاملی از تمام پارامترهای پرس و جو و کارهایی که انجام می دهند را می توان در راهنمای مرجع Core Reporting API یافت. همچنین پارامترهای ابعاد و متریک به شما این امکان را می دهند که مشخص کنید چه داده هایی را از Google Analytics بازیابی کنید. یک لیست کامل را می توان در صفحه مرجع ابعاد و معیارها یافت.
ایجاد یک درخواست داده Core Reporting API
هنگامی که یک پرس و جو را تعریف کردید، روش آن را برای ارسال پرس و جو به سرورهای Google Analytics execute
می کنید.
جاوا
try { apiQuery.execute(); // Success. Do something cool! } catch (GoogleJsonResponseException e) { // Catch API specific errors. handleApiError(e); } catch (IOException e) { // Catch general parsing network errors. e.printStackTrace(); }
اگر ترجیح می دهید به جای آن به پاسخ API خام دسترسی داشته باشید، از متد executeUnparsed()
استفاده کنید:
HttpResponse response = apiQuery.executeUnparsed();
پایتون
try: results = get_api_query(service).execute() print_results(results) except TypeError, error: # Handle errors in constructing a query. print ('There was an error in constructing your query : %s' % error) except HttpError, error: # Handle API service errors. print ('There was an API error : %s : %s' % (error.resp.status, error._get_reason()))
PHP
try { $results = queryCoreReportingApi(); // Success. Do something cool! } catch (apiServiceException $e) { // Handle API service exceptions. $error = $e->getMessage(); }
جاوا اسکریپت
function makeApiCall() { // ... apiQuery.execute(handleCoreReportingResults); } function handleCoreReportingResults(results) { if (!results.error) { // Success. Do something cool! } else { alert('There was an error: ' + results.message); } }
این مثال از مرحله قبل است که در آن یک پرس و جو Core Reporting API ایجاد شد. در این مرحله کوئری اجرا می شود. پارامتر متد execute
اشاره ای به یک تابع callback است که پس از بازگرداندن داده ها از API اجرا می شود.
پس از بازگشت API با نتایج، تابع callback اجرا می شود و داده ها از API ارسال می شود. اگر خطایی رخ دهد، نتایج حاوی یک ویژگی به نام error
است.
در این مثال، بررسی می شود که آیا error
وجود دارد یا اینکه آیا API با موفقیت بازگشته است.
اگر پرس و جو موفقیت آمیز بود، API داده های درخواستی را برمی گرداند. در صورت بروز هر گونه خطایی، API یک کد وضعیت خاص و پیامی که خطا را توصیف می کند، برمی گرداند. همه برنامه ها باید به درستی خطاها را دریافت و رسیدگی کنند.
کار با نتایج API
اگر پرس و جو Core Reporting API موفقیت آمیز بود، API با داده های گزارش Analytics و همچنین سایر اطلاعات مرتبط در مورد داده ها برمی گردد.
داده های گزارش تجزیه و تحلیل
داده های اصلی برگردانده شده از API را می توان به عنوان یک جدول با 2 نوع داده اصلی در نظر گرفت:
- عنوانی که انواع مقادیر را در هر ستون توصیف می کند
- ردیف های داده در جدول
داده های هدر ستون
هر پاسخ API حاوی یک فیلد هدر ستون است که اطلاعات سرصفحه جدول را نشان می دهد. فیلد لیستی (یا آرایه ای) از اشیاء است که در آن هر شیء نوع داده در ستون را توصیف می کند. ترتیب ستون ها ابعاد ستون هایی است که به دنبال آن ستون های متریک به همان ترتیبی که در جستار اصلی مشخص شده است.
جاوا
private void printColumnHeaders(GaData gaData) { System.out.println("Column Headers:"); for (GaDataColumnHeaders header : gaData.getColumnHeaders()) { System.out.println("Column Name: " + header.getName()); System.out.println("Column Type: " + header.getColumnType()); System.out.println("Column Data Type: " + header.getDataType()); } }
پایتون
def print_column_headers(): headers = results.get('columnHeaders') for header in headers: # Print Dimension or Metric name. print 'Column name = %s' % header.get('name')) print 'Column Type = %s' % header.get('columnType') print 'Column Data Type = %s' % header.get('dataType')
PHP
private function printColumnHeaders(&results) { $html = ''; $headers = $results->getColumnHeaders(); foreach ($headers as $header) { $html .= <<<HTML Column Name = {$header->getName()} Column Type = {$header->getColumnType()} Column Data Type = {$header->getDataType()} HTML; print $html; }
جاوا اسکریپت
function printColumnHeaders(results) { var output = []; for (var i = 0, header; header = results.columnHeaders[i]; ++i) { output.push( 'Name = ', header.name, '\n', 'Column Type = ', header.columnType, '\n', 'Data Type = ', header.dataType, '\n' ); } alert(output.join('')); }
داده های ردیف
داده های اصلی بازگردانده شده از API به صورت یک List
دو بعدی از رشته ها برگردانده می شود. لیست بیرونی تمام ردیف های داده را نشان می دهد. هر لیست داخلی یک سطر را نشان میدهد که ترتیب سلولها در یک ردیف با فیلدهای موجود در شی هدر ستون که در بالا توضیح داده شد یکسان است.
از آنجایی که دادهها در هر سلول بهعنوان یک رشته برگردانده میشوند، فیلد DataType
در هر شی هدر ستون بسیار مفید است زیرا میتوان از آن برای تجزیه مقادیر رشته به یک نوع مناسب استفاده کرد. پاسخ API فراداده را برای همه انواع داده های ممکن مشاهده کنید.
مثال های زیر هم سرصفحه ها و هم ردیف های جدول را چاپ می کنند.
جاوا
private void printDataTable(GaData gaData) { if (gaData.getTotalResults() > 0) { System.out.println("Data Table:"); // Print the column names. for (GaDataColumnHeaders header : gaData.getColumnHeaders()) { System.out.format("%-32s", header.getName() + '(' + header.getDataType() + ')'); } System.out.println(); // Print the rows of data. for (List<String> rowValues : gaData.getRows()) { for (String value : rowValues) { System.out.format("%-32s", value); } System.out.println(); } } else { System.out.println("No Results Found"); }
پایتون
def print_data_table(results): # Print headers. output = [] for header in results.get('columnHeaders'): output.append('%30s' % header.get('name')) print ''.join(output) # Print rows. if results.get('rows', []): for row in results.get('rows'): output = [] for cell in row: output.append('%30s' % cell) print ''.join(output) else: print 'No Results Found'
PHP
private function printDataTable(&$results) { if (count($results->getRows()) > 0) { $table .= '<table>'; // Print headers. $table .= '<tr>'; foreach ($results->getColumnHeaders() as $header) { $table .= '<th>' . $header->name . '</th>'; } $table .= '</tr>'; // Print table rows. foreach ($results->getRows() as $row) { $table .= '<tr>'; foreach ($row as $cell) { $table .= '<td>' . htmlspecialchars($cell, ENT_NOQUOTES) . '</td>'; } $table .= '</tr>'; } $table .= '</table>'; } else { $table .= '<p>No Results Found.</p>'; } print $table; }
جاوا اسکریپت
function printRows(results) { output = []; if (results.rows && results.rows.length) { var table = ['<table>']; // Put headers in table. table.push('<tr>'); for (var i = 0, header; header = results.columnHeaders[i]; ++i) { table.push('<th>', header.name, '</th>'); } table.push('</tr>'); // Put cells in table. for (var i = 0, row; row = results.rows[i]; ++i) { table.push('<tr><td>', row.join('</td><td>'), '</td></tr>'); } table.push('</table>'); output.push(table.join('')); } else { output.push('<p>No Results Found</p>'); } alert(output.join('')); }
گزارش اطلاعات
همراه با داده های جدول اصلی، داده های بازگردانده شده از API حاوی اطلاعات سطح بالایی در مورد پاسخ است. می توانید آن را با استفاده از:
جاوا
private void printResponseInfo(GaData gaData) { System.out.println("Contains Sampled Data: " + gaData.getContainsSampledData()); System.out.println("Kind: " + gaData.getKind()); System.out.println("ID:" + gaData.getId()); System.out.println("Self link: " + gaData.getSelfLink()); }
پایتون
def print_response_info(results): print 'Contains Sampled Data = %s' % results.get('containsSampledData') print 'Kind = %s' % results.get('kind') print 'ID = %s' % results.get('id') print 'Self Link = %s' % results.get('selfLink')
PHP
private function printReportInfo(&$results) { $html = <<<HTML <pre> Contains Sampled Data = {$results->getContainsSampledData()} Kind = {$results->getKind()} ID = {$results->getId()} Self Link = {$results->getSelfLink()} </pre> HTML; print $html; }
جاوا اسکریپت
function printReportInfo(results) { var output = []; output.push( 'Contains Sampled Data = ', results.containsSampledData, '\n', 'Kind = ', results.kind, '\n', 'ID = ', results.id, '\n', 'Self Link = ', results.selfLink, '\n'); alert(output.join('')); }
فیلد containsSampledData
مهم است زیرا توضیح می دهد که آیا پاسخ API نمونه برداری شده است یا خیر. نمونهبرداری میتواند بر نتایج دادههای شما تأثیر بگذارد و یک دلیل متداول برای عدم تطابق مقادیر بازگشتی از API با رابط وب است. برای جزئیات بیشتر به راهنمای مفهوم نمونه برداری مراجعه کنید.
مشاهده اطلاعات (نمایه).
هر پاسخ شامل گروهی از پارامترها است که نشان می دهد حساب، ویژگی وب و نمای (نمایه) متعلق به این داده ها است.
جاوا
private void printProfileInfo(GaData gaData) { GaDataProfileInfo profileInfo = gaData.getProfileInfo(); System.out.println("Account ID: " + profileInfo.getAccountId()); System.out.println("Web Property ID: " + profileInfo.getWebPropertyId()); System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId()); System.out.println("View (Profile) ID: " + profileInfo.getProfileId()); System.out.println("View (Profile) Name: " + profileInfo.getProfileName()); System.out.println("Table ID: " + profileInfo.getTableId()); }
پایتون
def print_profile_info(result): info = results.get('profileInfo') print 'Account Id = %s' % info.get('accountId') print 'Web Property Id = %s' % info.get('webPropertyId') print 'Web Property Id = %s' % info.get('internalWebPropertyId') print 'View (Profile) Id = %s' % info.get('profileId') print 'Table Id = %s' % info.get('tableId') print 'View (Profile) Name = %s' % info.get('profileName')
PHP
private function printProfileInformation(&$results) { $profileInfo = $results->getProfileInfo(); $html = <<<HTML <pre> Account ID = {$profileInfo->getAccountId()} Web Property ID = {$profileInfo->getWebPropertyId()} Internal Web Property ID = {$profileInfo->getInternalWebPropertyId()} Profile ID = {$profileInfo->getProfileId()} Table ID = {$profileInfo->getTableId()} Profile Name = {$profileInfo->getProfileName()} </pre> HTML; print $html; }
جاوا اسکریپت
function printProfileInfo(results) { var output = []; var info = results.profileInfo; output.push( 'Account Id = ', info.accountId, '\n', 'Web Property Id = ', info.webPropertyId, '\n', 'View (Profile) Id = ', info.profileId, '\n', 'Table Id = ', info.tableId, '\n', 'View (Profile) Name = ', info.profileName); alert(output.join('')); }
هر یک از این شناسه ها مربوط به نهادهای مختلف در سلسله مراتب مدیریت API است. میتوانید از این شناسهها برای تشکیل پرسوجوهای مدیریت API برای دریافت اطلاعات پیکربندی اضافی درباره نما (نمایه) استفاده کنید. برای مثال، میتوانید از مجموعه اهداف مدیریت API پرس و جو کنید تا ببینید کدام اهداف به همراه نام اهداف پیکربندی شدهشان فعال هستند.
استعلام اطلاعات
هر پاسخ Core Reporting API حاوی یک شی است که حاوی تمام مقادیر پارامتر query است که برای ایجاد پاسخ استفاده می شود.
جاوا
private void printQueryInfo(GaData gaData) { GaDataQuery query = gaData.getQuery(); System.out.println("Ids: " + query.getIds()); System.out.println("Start Date: " + query.getStartDate()); System.out.println("End Date: " + query.getEndDate()); System.out.println("Metrics: " + query.getMetrics()); // List System.out.println("Dimensions: " + query.getDimensions()); System.out.println("Sort: " + query.getSort()); // List System.out.println("Segment: " + query.getSegment()); System.out.println("Filters: " + query.getFilters()); System.out.println("Start Index: " + query.getStartIndex()); System.out.println("Max Results: " + query.getMaxResults()); }
پایتون
def print_query_info(results): query = results.get('query') for key, value in query.iteritems(): print '%s = %s' % (key, value)
PHP
private function printQueryParameters(&$results) { $query = $results->getQuery(); $html = '<pre>'; foreach ($query as $paramName => $value) { $html .= "$paramName = $value\n"; } $html .= '</pre>'; print $html; }
جاوا اسکریپت
function printQuery(results) { output = []; for (var key in results.query) { output.push(key, ' = ', results.query[key], '\n'); } alert(output.join('')); }
metrics
و sort
به عنوان مقادیر در یک لیست برگردانده می شوند، در حالی که سایر پارامترها به عنوان رشته ها برگردانده می شوند.
اطلاعات صفحه بندی
هر درخواست Core Reporting API ممکن است با صدها هزار ردیف داده Google Analytics مطابقت داشته باشد. Core Reporting API فقط یک زیرمجموعه را در یک زمان معین برمی گرداند که می توان به آن به عنوان یک صفحه داده اشاره کرد. شما از فیلدهای صفحه بندی برای بازیابی تمام صفحات داده استفاده می کنید.
جاوا
private void printPaginationInfo(GaData gaData) { System.out.println("Items Per Page: " + gaData.getItemsPerPage()); System.out.println("Total Results: " + gaData.getTotalResults()); System.out.println("Previous Link: " + gaData.getPreviousLink()); System.out.println("Next Link: " + gaData.getNextLink()); }
پایتون
def print_pagination_info(results): print 'Items per page = %s' % results.get('itemsPerPage') print 'Total Results = %s' % results.get('totalResults') print 'Previous Link = %s' % results.get('previousLink') print 'Next Link = %s' % results.get('nextLink')
PHP
private function getPaginationInfo(&$results) { $html = <<<HTML <pre> Items per page = {$results->getItemsPerPage()} Total results = {$results->getTotalResults()} Previous Link = {$results->getPreviousLink()} Next Link = {$results->getNextLink()} </pre> HTML; print $html; }
جاوا اسکریپت
function printPaginationInfo(results) { var output = []; output.push( 'Items Per Page = ', results.itemsPerPage, '\n', 'Total Results = ', results.totalResults, '\n', 'Previous Link = ', results.previousLink, '\n', 'Next Link = ', results.nextLink, '\n'); alert(output.join('')); }
فیلد totalResults
تعداد کل ردیف های داده ای را نشان می دهد که پرس و جو شما در Google Analytics مطابقت دارد. این می تواند بیشتر از تعداد واقعی سطرهای بازگردانده شده در یک صفحه از پاسخ باشد. فیلد itemsPerPage
نشان دهنده تعداد ردیف های برگشتی در این صفحه است.
پارامترهای previousLink
و nextLink
فقط در صورتی وجود دارند که صفحه قبلی یا بعدی وجود داشته باشد. این پیوندها را بررسی کنید تا ببینید آیا میتوان صفحات بیشتری از دادهها را از Core Reporting API بازیابی کرد یا خیر.
مجموع همه نتایج
همانطور که در بخش اطلاعات صفحه بندی در بالا ذکر شد، یک پرس و جو به Core Reporting API می تواند با بسیاری از ردیف های داده در Google Analytics مطابقت داشته باشد، اما فقط زیر مجموعه ای از داده ها را برمی گرداند. مجموع مقادیر متریک برای تمام ردیف های مطابقت داده شده در شی totalsForAllResults
برگردانده می شود. این داده ها برای محاسبه میانگین ها مفید است.
جاوا
private void printTotalsForAllResults(GaData gaData) { MaptotalsMap = gaData.getTotalsForAllResults(); for (Map.Entry entry : totalsMap.entrySet()) { System.out.println(entry.getKey() + " : " + entry.getValue()); } }
پایتون
def print_totals_for_all_results(results): totals = results.get('totalsForAllResults') for metric_name, metric_total in totals.iteritems(): print 'Metric Name = %s' % metric_name print 'Metric Total = %s' % metric_total
PHP
private function printTotalsForAllResults(&$results) { $totals = $results->getTotalsForAllResults(); foreach ($totals as $metricName => $metricTotal) { $html .= "Metric Name = $metricName\n"; $html .= "Metric Total = $metricTotal"; } print $html; }
جاوا اسکریپت
function printTotalsForAllResults(results) { var output = []; var totals = results.totalsForAllResults; for (metricName in totals) { output.push( 'Metric Name = ', metricName, '\n', 'Metric Total = ', totals[metricName], '\n'); } alert(output.join('')); }
نمونه های کاری
برای دیدن نمونههای کار کامل، Core Reporting API Sample را در فهرست نمونه هر کتابخانه مشتری بررسی کنید.
جاوا
Google API Java Client Core Reporting نمونه API
پایتون
Google API Client Python Core Reporting نمونه API
PHP
Google API Client PHP Core Reporting نمونه API
جاوا اسکریپت
نمونه API گزارش هسته کتابخانه سرویس گیرنده Google API JavaScript