מסמך זה מסביר כיצד להשתמש ב-Core Reporting API כדי לגשת לנתוני Google Analytics.
מבוא
ה-Core Reporting API מספק גישה לנתונים בטבלאות בדוחות הרגילים של Google Analytics. כדי לגשת לנתונים, יוצרים שאילתה שמציינת את התצוגה (פרופיל), תאריכי ההתחלה והסיום והמאפיינים והמדדים שמהם מורכבת כותרות העמודות בטבלה. השאילתה הזו נשלחת אל ה-Core Reporting API וה-Core Reporting API מחזיר את כל הנתונים בצורת טבלה.
אם אתם משתמשים חדשים ב-API, כדאי לקרוא את הסקירה הכללית על Core Reporting API כדי לקבל הסבר על ה-API הראשי לדיווח ועל הנתונים שהוא מספק.
לפני שתתחיל
במדריך זה נדגים כיצד לגשת אל Google Analytics API באמצעות שפות Java, Python, PHP ו-JavaScript.
- אפשר לעיין בדף ספריות לקוחות כדי לראות רשימה מלאה של ספריות לקוח ספציפיות שמתאימות ל-API.
- יש לקרוא את מדריך העזר כדי לגשת ל-API ללא ספריית לקוח.
כל ספריית לקוח מספקת אובייקט שירות יחיד של ניתוח נתונים כדי לגשת לכל נתוני Core Reporting API. כדי ליצור את אובייקט השירות, בדרך כלל צריך לבצע את השלבים הבאים:
- יש לרשום את האפליקציה ב- Google API Console.
- מאשרים את הגישה לנתוני Google Analytics.
- יוצרים אובייקט שירות של Analytics.
אם לא ביצעת את השלבים האלה, יש להפסיק ולקרוא את המדריך של Google Analytics API. המדריך הזה יסביר לך את השלבים הראשוניים ליצירת אפליקציה ב-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
מופעל לטעינה של סיווג שירות ניתוח הנתונים.
בסיום הפעולה, האובייקט gapi.client.analytics
צריך להיות קיים ב-DOM ומוכן לשימוש לשליחת שאילתות ל-Reporting Reporting API.
לאחר שיוצרים אובייקט שירות לניתוח נתונים, אפשר לשלוח בקשות ל-API Reporting Core.
הערה: אפשר להשתמש גם באובייקט שירות הניתוח כדי לגשת אל Management API.
סקירה כללית
בדרך כלל, אפליקציה שמשתמשת ב-Core Reporting API תבצע שני שלבים:
- שליחת שאילתה לממשק ה-API הראשי לדיווח
- עבודה עם תוצאות ה-API
בואו נראה את שני השלבים.
שליחת שאילתה לממשק ה-API הראשי לדיווח
יצירת שאילתה ב-Core Reporting API
האובייקט של שירות ניתוח הנתונים מכיל שיטה לבניית שאילתה ב-Core Reporting 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
לא רק יוצרת שאילתה ב-Core Reporting 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
.
ניתן למצוא רשימה מלאה של כל הפרמטרים של השאילתות והפעולות שהם מבצעים ב מדריך העזר של Core Reporting API. בנוסף, הפרמטרים של מאפיינים ומדדים מאפשרים לציין אילו נתונים לאחזר מ-Google Analytics. ניתן למצוא רשימה מלאה בדף מאפיינים ומדדים.
שליחת בקשה לנתונים של Core Reporting API
אחרי שמגדירים שאילתה, אפשר להפעיל אותה בשיטה 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); } }
הדוגמה הבאה מופיעה מהשלב הקודם שבו נוצרה שאילתת Core API. בשלב זה, השאילתה מופעלת.
הפרמטר בשיטה execute
הוא הפניה לפונקציית קריאה חוזרת (callback) שתבוצע אחרי שהנתונים יוחזרו מה-API.
אחרי שה-API חוזר עם התוצאות, פונקציית הקריאה החוזרת מופעלת
ומעבירה את הנתונים מה-API. אם תתרחש שגיאה, התוצאות יכללו
נכס בשם error
.
בדוגמה הזו מתבצעת בדיקה כדי לראות אם error
קיים או אם ה-API הוחזר בהצלחה.
אם השאילתה הושלמה, ה-API יחזיר את הנתונים הנדרשים. אם מתרחשות שגיאות, ה-API מחזיר קוד סטטוס ספציפי והודעה המתארת את השגיאה. כל האפליקציות אמורות לאתר שגיאות ולטפל בהן כראוי.
עבודה עם תוצאות ה-API
אם שאילתת Core Reporting API הצליחה, ה-API יחזור עם נתוני הדיווח של Analytics יחד עם מידע קשור נוסף לגבי הנתונים.
נתוני הדוחות של Analytics
הנתונים העיקריים שמוחזרים מה-API יכולים להיחשב כטבלה שמכילה שני סוגים עיקריים של נתונים:
- הכותרת שמתארת את סוגי הערכים בכל עמודה.
- שורות הנתונים בטבלה
נתוני כותרת עמודה
כל תגובת 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, ולקבל מידע נוסף על ההגדרה בתצוגה המפורטת (פרופיל). לדוגמה, ניתן להריץ שאילתה לגבי אוסף היעדים לניהול של ממשק 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
מוחזרים כערכים ברשימה, והפרמטרים האחרים
מוחזרים כמחרוזות.
פרטי העימוד
כל בקשה של Core Reporting API עשויה להתאים למאות אלפי שורות של נתונים ב-Google Analytics. בכל שלב, ה-API 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('')); }
דוגמאות לעבודה
כדי לראות את הדוגמאות המלאות לעבודות, יש לבדוק את הדגימה העיקרית של ממשק ה-API לדיווח בכל ספריית לקוח של #.
Java
ספריית לקוחות Google API Java Core Reporting API Sample
Python
ספריית לקוחות Google API Python Core Reporting API Sample
PHP
ספריית לקוח PHP ב-Google API דוגמה של ממשק ה-API הראשי לדיווח
JavaScript
ספריית לקוח JavaScript ב-API של Google דוגמה לממשק API של דיווח ליבה