מסמך זה מסביר כיצד להשתמש ב-Core Reporting API כדי לגשת לנתוני Google Analytics.
מבוא
ה-Core Reporting API מאפשר גישה לנתונים שבטבלה בדוחות הרגילים ובדוחות בהתאמה אישית של Google Analytics. כדי לגשת לנתונים, צריך ליצור שאילתה שמציינת את הפרטים הבאים: התצוגה המפורטת (פרופיל), תאריכי ההתחלה והסיום והמאפיינים והמדדים שמהם מורכבת כותרות העמודות בטבלה. השאילתה הזו נשלחת אל Core Reporting API וה-Core Reporting API מחזיר את כל הנתונים בצורת טבלה.
משתמשים חדשים ב-API? מומלץ לקרוא את הסקירה הכללית בנושא Core Reporting API כדי להכיר את השימוש ב-Core Reporting API ואת הנתונים שהוא מספק.
לפני שתתחיל
מדריך זה מדגים איך לגשת ל-Google Analytics API באמצעות שפות התכנות Java, Python, PHP ו-JavaScript.
- בדף ספריות לקוח אפשר למצוא רשימה מלאה של ספריות לקוח ספציפיות לשפת תכנות שעובדות עם ה-API.
- כדי לגשת ל-API ללא ספריית לקוח, קראו את מדריך העזר.
כל ספריית לקוח מספקת אובייקט שירות יחיד של ניתוח נתונים כדי לגשת לכל הנתונים של Core Reporting API. בדרך כלל, על מנת ליצור את אובייקט השירות:
- רשום את האפליקציה שלך ב מסוף Google API.
- הרשאת גישה לנתוני Google Analytics.
- יוצרים אובייקט שירות של Analytics.
אם לא השלמת את השלבים האלה, כדאי לעצור ולקרוא את המדריך ל-API של Google Analytics. במדריך הזה מפורטים השלבים הראשוניים ליצירת אפליקציה ב-Google Analytics API. בסיום התהליך, אפשר להשתמש במדריך הזה כדי לבצע משימות בעולם האמיתי.
קטע הקוד הבא מכיל משתנה לאחסון אובייקט שירות מורשה.
Java
Analytics analytics = // Read Hello Analytics Tutorial for details.
Python
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
של הלקוח
כפי שמוצג בדוגמה שלמעלה.
JavaScript
<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>
תג הסקריפט הראשון טוען את ספריית ה-JavaScript של Google API. לאחר
הטעינה, loadLib
מופעל כדי לטעון את מחלקת השירות של Analytics.
בסיום התהליך, האובייקט gapi.client.analytics
אמור להיות קיים ב-DOM ומוכן לשימוש כדי לשלוח שאילתות לגבי Core Reporting API.
אחרי שיוצרים אובייקט של שירות לניתוח נתונים, אפשר לשלוח בקשות ל-Core Reporting API.
הערה: אפשר להשתמש באובייקט השירות של ניתוח הנתונים גם כדי לגשת ל-Management API.
סקירה
אפליקציה שמשתמשת ב-Core Reporting API יבצע בדרך כלל שני שלבים:
- שליחת שאילתה ל-Core Reporting API
- עבודה עם תוצאות ה-API
נבחן את שני השלבים.
שליחת שאילתה ל-Core Reporting API
בניית שאילתה של ה-Reporting API המרכזי
אובייקט השירות של ניתוח הנתונים מכיל שיטה ליצירת שאילתה של ממשק ה-API הראשי לדיווח.
כל שאילתה של Core Reporting API מכילה קבוצה של פרמטרים שמציינים אילו נתונים להחזיר.אחד מהפרמטרים החשובים ביותר של שאילתה הוא הפרמטר ids
, או מזהה הטבלה. הפרמטר הזה מציין מאיזו תצוגה מפורטת (פרופיל) ב-Google Analytics יאחזר נתונים. הערך הוא בפורמט ga:xxx
, כאשר xxx
הוא מזהה התצוגה המפורטת (הפרופיל).
Java
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);
Python
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
לא רק יוצרת שאילתה של ממשק ה-API הראשי לדיווח, אלא גם מבצעת את הבקשה ל-API.
JavaScript
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
אחרי שספריית הלקוח של JavaScript נטענת. בפנים, הפונקציה יוצרת שאילתה חדשה ב-Google Analytics API ומאחסנת את האובייקט במשתנה apiQuery
.
רשימה מלאה של כל הפרמטרים של שאילתות והפעולות שהם מבצעים זמינה במדריך הראשי של ממשק ה-API. בנוסף, הפרמטרים של המאפיינים והמדדים מאפשרים לציין אילו נתונים לאחזר מ-Google Analytics. אפשר למצוא רשימה מלאה בדף העזר של מאפיינים ומדדים.
יצירת בקשת נתונים ל-Core Reporting API
אחרי שמגדירים שאילתה, אפשר לקרוא ל-method execute
לשלוח את השאילתה לשרתים של Google Analytics.
Java
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();
Python
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(); }
JavaScript
function makeApiCall() { // ... apiQuery.execute(handleCoreReportingResults); } function handleCoreReportingResults(results) { if (!results.error) { // Success. Do something cool! } else { alert('There was an error: ' + results.message); } }
הדוגמה הזו נובעת מהשלב הקודם שבו נוצרה שאילתת ליבה של Reporting API. בשלב הזה השאילתה מופעלת.
הפרמטר ל-method execute
הוא הפניה לפונקציית קריאה חוזרת
שתבוצע לאחר החזרת הנתונים מה-API.
אחרי שה-API חוזר עם התוצאות, פונקציית הקריאה החוזרת מופעלת ומעבירה את הנתונים מה-API. במקרה של שגיאה, התוצאות
יכילו מאפיין בשם error
.
בדוגמה הזו, אפשר לבדוק אם error
קיים או אם
ה-API הוחזר בהצלחה.
אם השאילתה הצליחה, ה-API יחזיר את הנתונים המבוקשים. אם יתרחשו שגיאות, ה-API יחזיר קוד סטטוס ספציפי והודעה שמתארת את השגיאה. כל האפליקציות צריכות לזהות שגיאות ולטפל בהן כראוי.
עבודה עם תוצאות ה-API
אם השאילתה של ה-Core Reporting API הסתיימה בהצלחה, ה-API יחזור עם נתוני הדיווח מ-Analytics וגם מידע קשור אחר על הנתונים.
נתוני דיווח ב-Analytics
אפשר להתייחס לנתונים העיקריים שמוחזרים מ-API כטבלה עם 2 סוגי נתונים עיקריים:
- הכותרת שמתארת את סוגי הערכים בכל עמודה
- שורות הנתונים בטבלה
נתונים של כותרות עמודה
כל תגובת API מכילה שדה של כותרת עמודה שמייצג את פרטי הכותרת של הטבלה. השדה הוא רשימה (או מערך) של אובייקטים שבהם כל אובייקט מתאר את סוג הנתונים בעמודה. סדר העמודות הוא עמודות של מאפיינים ואחריהן עמודות מדדים באותו סדר שצוין בשאילתה המקורית.
Java
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()); } }
Python
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; }
JavaScript
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 של המטא-נתונים מפורטים כל סוגי הנתונים האפשריים.
בדוגמאות הבאות אפשר להדפיס גם את הכותרות וגם את השורות של הטבלה.
Java
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"); }
Python
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; }
JavaScript
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 מכילים מידע כללי על התשובה. אפשר להדפיס אותה באמצעות:
Java
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()); }
Python
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; }
JavaScript
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 לא תואמים לממשק האינטרנט. לפרטים נוספים, אפשר לעיין במדריך המושגים דגימה.
הצגה של פרטי (פרופיל)
כל תגובה מכילה קבוצה של פרמטרים שמציינים את החשבון, נכס האינטרנט והתצוגה המפורטת (פרופיל) שאליהם שייכים הנתונים האלה.
Java
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()); }
Python
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; }
JavaScript
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 לניהול. אפשר להשתמש במזהים האלה כדי ליצור שאילתות של Management API כדי לקבל פרטי הגדרה נוספים של התצוגה המפורטת (פרופיל). לדוגמה, אפשר להריץ שאילתה על אוסף היעדים של Management API כדי לראות אילו יעדים פעילים ואת שמות היעדים המוגדרים שלהם.
פרטי השאילתה
כל תגובה של Core Reporting API מכילה אובייקט שמכיל את כל ערכי הפרמטרים של השאילתה ששימשו ליצירת התגובה.
Java
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()); }
Python
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; }
JavaScript
function printQuery(results) { output = []; for (var key in results.query) { output.push(key, ' = ', results.query[key], '\n'); } alert(output.join('')); }
הפרמטרים metrics
ו-sort
מוחזרים כערכים ברשימה, והפרמטרים
האחרים מוחזרים כמחרוזות.
פרטי העימוד
כל בקשה של ממשק ה-API הראשי לדיווח עשויה להתאים למאות אלפי שורות של נתונים ב-Google Analytics. ה-Core Reporting API יחזיר רק קבוצת משנה בכל זמן נתון, שנקרא דף יחיד של נתונים. כדי לאחזר את כל דפי הנתונים, צריך להשתמש בשדות העימוד.
Java
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()); }
Python
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; }
JavaScript
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
.
הנתונים האלה שימושיים לחישוב ממוצעים.
Java
private void printTotalsForAllResults(GaData gaData) { MaptotalsMap = gaData.getTotalsForAllResults(); for (Map.Entry entry : totalsMap.entrySet()) { System.out.println(entry.getKey() + " : " + entry.getValue()); } }
Python
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; }
JavaScript
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 בספרייה לדוגמה של כל ספריית לקוח.
Java
ספריית לקוח Java ב-Google API דוגמה ל-Core Reporting API
Python
ספריית לקוח Python ב-Google API דוגמה ל-Core Reporting API
PHP
ספריית לקוח PHP ב-Google API דוגמה ל-Core Reporting API
JavaScript
ספריית לקוח JavaScript ב-Google API דוגמה ל-Core Reporting API