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

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

  1. יש לרשום את האפליקציה ב- Google API Console.
  2. מאשרים את הגישה לנתוני Google Analytics.
  3. יוצרים אובייקט שירות של 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) {
  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(''));
}

דוגמאות לעבודה

כדי לראות את הדוגמאות המלאות לעבודות, יש לבדוק את הדגימה העיקרית של ממשק ה-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 של דיווח ליבה

מקור JavaScript