מדריך להעברת נתונים (מיגרציה)

במדריך הזה מפורטות הנחיות להעברת ה-Core Reporting API גרסה 3 אל Analytics Reporting API v4.

מבוא

כדי לנצל את התכונות החדשות שהושקו ב-Analytics Reporting API v4, עליך להעביר את הקוד לשימוש ב-API. כדי להקל על ההעברה, במדריך הזה מוצגות בקשות ב-Core Reporting API v3, ובקשות מקבילות ב-Analytics Reporting API v4.

העברה ל-Python

אם אתם מפתחי Python, תוכלו להשתמש בספריית העזרה של GAV4 ב-GitHub כדי להמיר בקשות של Google Analytics Core Reporting API v3 לבקשות של Analytics Reporting API v4

נקודות קצה (endpoints)

ל-Core Reporting API v3 ול-Analytics Reporting API v4 יש נקודות קצה ושיטות HTTP שונות:

נקודת קצה 3, גרסה 3

GET https://www.googleapis.com/analytics/v3/data/ga

נקודת קצה (endpoint) גרסה 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet

בדוגמאות הבאות משווים בין בקשה בגרסה 3 לבקשה המקבילה בגרסה 4:

v3

מסמכי עזר לגרסה 3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
    &start-date=2015-11-01&end-date=2015-11-06 \
    &metrics=ga:users&dimensions=ga:pagePath

v4

מסמכי עזר לגרסה 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    "viewId":"XXXX",
    "dateRanges":[
    {
      "startDate":"2015-11-01",
      "endDate":"2015-11-06"
    }],
    "metrics":[
    {
      "expression":"ga:users"
    }],
    "dimensions": [
    {
      "name":"ga:pagePath"
    }]
  }]
}

ספריות לקוח ושירות Discovery

אם אתם משתמשים ב-Python, ב-JavaScript או בספריית לקוח אחרת שמסתמכת על Google Discovery Service, עליכם לספק את המיקום של מסמך הגילוי של ה-Reporting API v4.

Python

from apiclient import discovery

...

# Build the Analytics Reporting API v4 authorized service object.
analyticsReporting = discovery.build(
  'analyticsreporting',
  'v4',
  http=http,
  discoveryServiceUrl='https://analyticsreporting.googleapis.com/$discovery/rest')

JavaScript

gapi.client.load(
  'https://analyticsreporting.googleapis.com/$discovery/rest',
  'v4'
).then(...)

ספריות הלקוח של Java ו-PHP מוכנות מראש, אבל אפשר ליצור אותן באמצעות שירות הגילוי ומחולל ממשקי ה-API של Google.

בקשות

בחומר העזר בנושא API v4 מתואר בפירוט המבנה של גוף הבקשה. בקטעים הבאים מתוארת ההעברה של פרמטרים של בקשה ב-v3 לפרמטרים של בקשה בגרסה 4.

הצגת המזהים

בגרסה 3, פרמטר ids שמקבל 'מזהה טבלה' הוא בפורמט ga:XXXX, כאשר XXXX הוא מזהה התצוגה המפורטת (הפרופיל). בגרסה 4, מזהה התצוגה המפורטת (הפרופיל) מצוין בשדה viewId בגוף הבקשה.

בדוגמאות הבאות משווים בין הפרמטר ids בבקשת v3 לבין השדה viewId בבקשה בגרסה v4:

v3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX

v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    "viewId":"XXXX",
    ...
  }]
}

טווחי תאריכים

ב-Analytics Reporting API v4 אפשר לציין כמה טווחי תאריכים בבקשה אחת. השדה dateRanges מציג רשימה של אובייקטים מסוג DateRange. בגרסה 3, משתמשים בפרמטרים start-date ו-end-date כדי לציין טווח תאריכים בבקשה.

בדוגמאות הבאות משווים בין הפרמטרים start-date ו-end-date בבקשת v3 לבין השדה dateRanges בבקשה של v4:

v3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
    &start-date=2015-11-01&end-date=2015-11-06 \
    ...

v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    "viewId":"XXXX",
    "dateRanges":[
    {
      "startDate":"2015-11-01",
      "endDate":"2015-11-06"
    }],
    ....
  }]
}

מדדים

הפרמטר metrics בגרסה 3 תואם לשדה metrics בגרסה 4, שכולל רשימה של אובייקטים Metric.

בדוגמאות הבאות משווים בין הפרמטרים metrics בבקשת v3 לבין השדה metrics בבקשת v4:

v3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
    &start-date=2015-11-01&end-date=2015-11-06 \
    &metrics=ga:users,ga:sessions \
    ...

v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    "viewId":"XXXX",
    "dateRanges":[
    {
      "startDate":"2015-11-01",
      "endDate":"2015-11-06"
    }],
    "metrics":[
    {
      "expression":"ga:users"
    },{
      "expression":"ga:sessions"
    }],
    ...
  }]
}

מאפיינים

הפרמטר dimensions v3 תואם לשדה dimensions v4, שמקבל רשימה של אובייקטים מסוג מאפיינים.

בדוגמאות הבאות משווים בין הפרמטרים dimensions בבקשת v3 לבין השדה dimensions בבקשת v4:

v3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
  &dimensions=ga:country,ga:browser&... \

v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    "dimensions": [
    {
      "name":"ga:country"
    },{
      "name":"ga:browser"
    }],
    ...
  }]
}

מיון

הפרמטר sort בגרסה 3 מקביל לשדה v4 של orderBys, שמקבל רשימה של אובייקטים מסוג OrderBy.

בגרסה 4, כדי למיין את התוצאות לפי ערך של מאפיין או מדד:

  • מספקים את השם או הכינוי שלו דרך השדה fieldName.
  • מציינים את סדר המיון (ASCENDING או DESCENDING) באמצעות השדה sortOrder.

בדוגמאות הבאות משווים בין הפרמטר sort בבקשה ב-v3 לבין השדה orderBy בבקשת v4. שתיהן ממיינות את המשתמשים בסדר יורד וגם מקורות לפי סדר אלפביתי:

v3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
  &sort=-ga:users,ga:source

v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    "orderBys": [
    {
      "fieldName": "ga:users",
      "sortOrder": "DESCENDING"
    },{
      "fieldName": "ga:source"
    }],
  }]
}

רמת הדגימה

הפרמטר samplingLevel של גרסה 3 תואם לשדה v4 samplingLevel. בגרסה 3, ערכי samplingLevel הקבילים הם FASTER, HIGHER_PRECISION ו-DEFAULT. בגרסה 4, ערכי samplingLevel הקבילים הם SMALL, LARGE ו-DEFAULT. חשוב לשים לב: FASTER בגרסה 3 השתנה ל-SMALL בגרסה 4, HIGHER_PRECISION ל-LARGE.

בדוגמאות הבאות משווים בין הפרמטר samplingLevel בבקשת v3 לבין השדה samplingLevel בבקשת v4:

v3

https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX ...\
samplingLevel=HIGHER_PRECISION

v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    "samplingLevel": "LARGE"
  }]
}

פלחים

הפרמטר segment בגרסה 3 תואם לשדה segments בגרסה 4, שכולל רשימה של אובייקטים Segment.

מזהי פלחים

בגרסה 4, כדי לבקש פלח לפי מזהה פלח, יוצרים אובייקט Segment ומציינים את המזהה שלו דרך השדה segmentId.

בדוגמאות הבאות משווים בין הפרמטר segment בבקשת v3 לבין השדה segments בבקשה של v4:

v3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=gaid::-11

v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [{
    ...
    "viewId": "XXXX",
    "segments": [{
      "segmentId": "gaid::-11"
    }]
  }]
}

פלחים דינמיים

בגרסה 4, כדי להגדיר הגדרות מורכבות יותר של פלחים, צריך להשתמש בשדה segments שכולל אובייקט DynamicSegment.

בדוגמאות הבאות משווים בין הפרמטר segment בבקשת v3 לבין השדה segments שמכיל אובייקט DynamicSegment בבקשת v4:

v3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral

v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [{
    ...
    "segments": [{
      "dynamicSegment": {
        "name": "segment_name",
        "sessionSegment": {
          "segmentFilters": [{
            "simpleSegment": {
              "orFiltersForSegment": [{
                "segmentFilterClauses": [{
                  "dimensionFilter": {
                    "dimensionName": "ga:medium",
                    "operator": "EXACT",
                    "expressions": [ "referral" ]
                  }
                }]
              }]
            }
          }]
        }
      }
    }]
  }]
}

אפשר לשלב בין תנאים ורצפים לפלח:

v3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=users::condition::ga:revenue>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile

v4

  "reportRequests": [{
      "dateRanges": [
            { "endDate": "2014-11-30", "startDate": "2014-11-01" }
      ],
      "metrics": [
          {"expression": "ga:pageviews"},
          {"expression": "ga:sessions"}
      ],
      "viewId": "XXXX",
      "dimensions":[{"name":"ga:medium"}, {"name":"ga:segment"}],
      "segments": [{
        "dynamicSegment": {
        "name": "segment_name",
        "userSegment": {
          "segmentFilters": [{
            "simpleSegment": {
              "orFiltersForSegment": [{
                "segmentFilterClauses": [{
                  "metricFilter": {
                    "metricName": "ga:sessions",
                    "operator": "GREATER_THAN",
                    "comparisonValue": "10"
                  }
                }]
              }]
            }
          },
          {
            "sequenceSegment": {
              "segmentSequenceSteps": [{
                "orFiltersForSegment": [{
                  "segmentFilterClauses": [{
                    "dimensionFilter": {
                      "dimensionName": "ga:deviceCategory",
                      "operator": "EXACT",
                      "expressions": ["desktop"]
                    }
                  }]
                }],
                "matchType": "PRECEDES"
              },{
                "orFiltersForSegment": [{
                  "segmentFilterClauses": [{
                    "dimensionFilter": {
                      "dimensionName": "ga:deviceCategory",
                      "operator": "EXACT",
                      "expressions": ["mobile"]
                    }
                  }]
                }]
              }]
            }
          }]
        }
      }
    }]
  }]

תחביר פלחים v3 בגרסה 4

השדה segmentId ב-v4 API תומך בתחביר הפלחים ב-v3 API.

הדוגמאות הבאות מראות איך השדה segment בבקשת v3 נתמך על ידי השדה segmentId בבקשה המקבילה בגרסה 4:

v3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral

v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [{
    ...
    "viewId": "XXXX",
    "segments": [{
      "segmentId": "sessions::condition::ga:medium==referral"
    }]
  }]
}

מסננים

גרסה 4 משתמשת ב-dimensionFilterClauses כדי לסנן מאפיינים וב-metricFilterClauses כדי לסנן מדדים. השדה dimensionFilterClauses מכיל רשימה של אובייקטים ב-DimensionFilter ו-metricFilterClauses מכיל רשימה של אובייקטים MetricFilter.

בדוגמאות הבאות משווים בין הפרמטר filters בבקשת v3 לבין השדה dimensionFilterClauses בבקשה של v4:

v3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
  &start-date=2015-06-01&end-date=2015-07-31&metrics=ga:users& \
  dimensions=ga:browser&filters=ga:browser==Firefox

v4

  "reportRequests": [{
      "dateRanges": [
            { "endDate": "2014-11-30", "startDate": "2014-11-01" }
      ],
      "metrics": [
          {"expression": "ga:pageviews"},
          {"expression": "ga:sessions"}
      ],
      "viewId": "XXXX",
      "dimensions":[{"name":"ga:browser"}, {"name":"ga:country"}],
      "dimensionFilterClauses": [{
           "filters": [{
                "dimension_name": "ga:browser",
                "operator": "EXACT",
                "expressions": ["Firefox"]
            }]
      }]
  }]

תחביר של מסנני v3 ב-v4

למרות שהשדה filtersExpression בגרסה 4 תומך בתחביר filters בגרסה 3, כדאי להשתמש ב-dimensionFilterClauses וב-metricFilterClauses כדי לסנן מאפיינים ומדדים.

הדוגמאות הבאות מראות איך השדה filters בבקשת v3 נתמך על ידי השדה filtersExpression בבקשה המקבילה בגרסה 4:

v3

GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga%XXXX \
&filters=ga:browser==Firefox

v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [{
    ...
    "filtersExpression": "ga:browser==Firefox"
  }]
}

שורות ריקות

הפרמטר v3 include-empty-rows תואם לשדה includeEmptyRows ב-v4. ערך ברירת המחדל של הפרמטר v3 הוא true, ובגרסה 4 הערך שמוגדר בשדה הוא false. אם לא הגדרתם את הערך ב-v3, תצטרכו להגדיר את הערך כ-true בגרסה 4.

בדוגמאות הבאות מוצגת השוואה בין הפרמטר include-empty-rows בבקשת v3 לבין השדה includeEmptyRows בבקשת גרסה 4:

v3

https://www.googleapis.com/analytics/v3/data/ga? ...\
    &include-empty-rows=true

v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    "includeEmptyRows": "true",
  }]
}

חלוקה לדפים

v4 משתמשת בשדות pageToken ו-pageSize כדי לעבור בין מספר גדול של תוצאות. השדה pageToken מתקבל מהמאפיין nextPageToken של אובייקט תגובה.

בדוגמאות הבאות משווים בין הפרמטרים start-index ו-max-results בבקשת v3 לשדות pageToken ו-pageSize בבקשת v4:

v3

https://www.googleapis.com/analytics/v3/data/ga? ...\
    &start-index=10001&max-results=10000

v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":[
  {
    ...
    # Taken from `nextPageToken` of a previous response.
    "pageToken": "10000",
    "pageSize": "10000",
  }]
}

פרמטרים רגילים

ב-Analytics Reporting API v4 יש תמיכה ברוב הפרמטרים הרגילים של שאילתות ב-v3 API, מלבד הפרמטרים userIp ו-callback.

בדוגמאות הבאות משווים בין הפרמטר quotaUser בבקשת v3 לבין הפרמטר הזה בבקשת v4:

נקודת קצה 3, גרסה 3

GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2

נקודת קצה (endpoint) גרסה 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2

תשובות

מכיוון שגרסה 4 מאפשרת לשלוח מספר אובייקטים מסוג ReportRequest בבקשת HTTP אחת, מקבלים בתגובה מערך של אובייקטים מהדוח. על כל ReportRequest שנשלח, אתם מקבלים דיווח תואם.

דוחות

דוח של גרסה 4 כולל שלושה שדות ברמה העליונה: columnHeader, data ו-nextPageToken.

מכיוון שגוף התגובה v4 לא כולל תגובות לכל הפרמטרים של השאילתה כמו בתגובה ב-v3, על מנת לקבל תשובה לפרמטר ספציפי של שאילתה, אפליקציית הלקוח צריכה להוסיף את הפרמטר הזה ל-ReportRequest.

התייחסנו כבר ל-nextPageToken בקטע עימוד, אז נתחיל לבחון את האובייקט columnHeader.

כותרת עמודה

כותרת העמודה מכילה רשימה של מאפיינים בעלי שם ואובייקט MetricHeader, שמכיל רשימה של אובייקטים MetricHeaderEntry. כל אובייקט MetricHeaderEntry מציין את המדד name ואת type שלו (מטבע, אחוז וכו') , שעוזרת לעצב את הפלט.

בדוגמאות הבאות משווים את השדה columnHeaders בתגובה v3 לשדה columnHeader בתגובה של v4:

v3

"columnHeaders": [
    {
        "name":"ga:source",
        "columnType":"DIMENSION",
        "dataType":"STRING"
    },{
        "name":"ga:city",
        "columnType":"DIMENSION",
        "dataType":"STRING"
    },{
        "name":"ga:sessions",
        "columnType":"METRIC",
        "dataType":"INTEGER"
    },{
        "name":"ga:pageviews",
        "columnType":
        "METRIC",
        "dataType":"INTEGER"
    }
]

v4

"columnHeader": {
    "dimensions": [
        "ga:source",
        "ga:city"
    ],
    "metricHeader": {
        "metricHeaderEntries": [
            {
                "name": "ga:pageviews",
                "type": "INTEGER"
            },
            {
                "name": "ga:sessions",
                "type": "INTEGER"
            }
        ]
    }
},

שורות בדוח

ה-Core Reporting API v3 מחזיר את נתוני הדוח במערך rows, שמכיל את המאפיינים והמדדים המבוקשים.

ב-Analytics Reporting API v4 מחזיר את נתוני הדוח באובייקט ReportRow, שמכיל מערך של מאפיינים ומערך של אובייקטים מסוג DateRangeValues, שכל אחד מהם מכיל טווח תאריכים אחד או שניים, כפי שמתואר בתרשים הבא:

שורות בדוח

שורות

v3

"rows": [
    [
        "google",
        "Philadelphia",
        "60",
        "5"
    ],
    [
        "google",
        "Johnstown",
        "21",
        "1"
    ],
    [
        "google",
        "Progress",
        "7",
        "1"
    ]
],

v4

"rows": [
    {
        "dimensions": [
            "google",
            "Philadelphia"
        ],
        "metrics": [
            {
                "values": [
                    "60",
                    "5"
                ]
            }
        ]
    },
    {
        "dimensions": [
            "google",
            "Johnstown"
        ],
        "metrics": [
            {
                "values": [
                    "21",
                    "1"
                ]
            }
        ]
    },
    {
        "dimensions": [
            "google",
            "Progress"
        ],
        "metrics": [
            {
                "values": [
                    "7",
                    "1"
                ]
            }
        ]
    }
],

הנתונים שנדגמו

במקרה שהתוצאות נדגמו, Core Reporting API v3 מחזיר את השדה הבוליאני containsSampledData, שמוגדר ל-true.

גרסה 4 של Analytics Reporting API לא מחזירה ערך בוליאני אם הנתונים נדגמו. במקום זאת, ה-API מחזיר את השדות samplesReadCounts ו-samplingSpaceSizes. אם התוצאות לא נדגמו, השדות האלה לא יוגדרו. הדוגמה הבאה של Python מראה איך לחשב אם דוח מכיל נתונים שנדגמו:

def ContainsSampledData(report):
  """Determines if the report contains sampled data.

   Args:
       report (Report): An Analytics Reporting API v4 response report.

  Returns:
      bool: True if the report contains sampled data.
  """
  report_data = report.get('data', {})
  sample_sizes = report_data.get('samplesReadCounts', [])
  sample_spaces = report_data.get('samplingSpaceSizes', [])
  if sample_sizes and sample_spaces:
    return True
  else:
    return False

למטה מוצגת תגובה לדוגמה שמכילה נתונים שנדגמו מבקשה עם שני טווחי תאריכים. התוצאות חושבו מכמעט 500,000 דגימות בשטח דגימה של כ-15 מיליון סשנים:

{
  "reports":
  [
    {
      "columnHeader": {
        ...
      },
      "data": {
        ...
        "samplesReadCounts": [ "499630","499630"],
        "samplingSpaceSizes": ["15328013","15328013"],
      }
    }
  ]
}

ניתוח התגובה של גרסה 4

הקוד לדוגמה הבא מנתח ומדפיס את התגובה של Analytics Reporting API v4:

Python

def printResponse(self, response):
  """Parses and prints the Analytics Reporting API v4 response"""

  for report in response.get('reports', []):
    columnHeader = report.get('columnHeader', {})
    dimensionHeaders = columnHeader.get('dimensions', [])
    metricHeaders = columnHeader.get('metricHeader', {}).get('metricHeaderEntries', [])
    rows = report.get('data', {}).get('rows', [])

    for row in rows:
      dimensions = row.get('dimensions', [])
      dateRangeValues = row.get('metrics', [])

      for header, dimension in zip(dimensionHeaders, dimensions):
        print header + ': ' + dimension

      for i, values in enumerate(dateRangeValues):
        print 'Date range (' + str(i) + ')'
        for metricHeader, value in zip(metricHeaders, values.get('values')):
          print metricHeader.get('name') + ': ' + value

Java

public static void printResponse(GetReportsResponse response) {

  for (Report report: response.getReports()) {
    ColumnHeader header = report.getColumnHeader();
    List<String> dimensionHeaders = header.getDimensions();
    List<MetricHeaderEntry> metricHeaders = header.getMetricHeader().getMetricHeaderEntries();
    List<ReportRow> rows = report.getData().getRows();

    for (ReportRow row: rows) {
      List<String> dimensions = row.getDimensions();
      List<DateRangeValues> metrics = row.getMetrics();
      for (int i = 0; i < dimensionHeaders.size() && i < dimensions.size(); i++) {
        System.out.println(dimensionHeaders.get(i) + ": " + dimensions.get(i));
      }

      for (int j = 0; j < metrics.size(); j++) {
        System.out.print("Date Range (" + j + "): ");
        DateRangeValues values = metrics.get(j);
        for (int k = 0; k < values.size() && k < metricHeaders.size(); k++) {
          System.out.println(metricHeaders.get(k).getName() + ": " + values.get(k));
        }
      }
    }
  }
}

טיפול בשגיאות

מכיוון שהפורמט של תגובת שגיאה ב-v4 שונה מזה שב-v3, עליכם לעדכן את הקוד כך שיטפל בתגובות לשגיאות v4.

בדוגמאות הבאות משווים בין תגובת שגיאה ב-v3 לתגובת השגיאה המקבילה ב-v4:

v3

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "insufficientPermissions",
    "message": "User does not have sufficient permissions for this profile.",

   }
  ],
  "code": 403,
  "message": "User does not have sufficient permissions for this profile."
 }
}

v4

{
 "error": {
  "code": 403,
  "message": "User does not have sufficient permissions for this profile.",
  "status": "PERMISSION_DENIED",
  "details": [
   {
    "@type": "type.googleapis.com/google.rpc.DebugInfo",
    "detail": "[ORIGINAL ERROR] generic::permission_denied: User does not have sufficient permissions for this profile. [google.rpc.error_details_ext] { message: \"User does not have sufficient permissions for this profile.\" }"
   }
  ]
 }
}