ממשק ה-API הראשי לדיווח – מדריך למפתחים

מסמך זה מסביר כיצד להשתמש ב-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. בדרך כלל, על מנת ליצור את אובייקט השירות:

  1. רשום את האפליקציה שלך ב מסוף Google API.
  2. הרשאת גישה לנתוני Google Analytics.
  3. יוצרים אובייקט שירות של 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) {
  Map totalsMap = 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

מקור JavaScript