יצירת דוח

זהו מדריך למפתחים בנושא Analytics Reporting API v4. למידע מפורט על ה-API, ראו הפניית API.

דוחות

Analytics Reporting API v4 מספק את השיטה batchGet כדי לגשת למשאב Reports. בקטעים הבאים מתוארים המבנה של גוף הבקשה עבור batchGet ואת המבנה של גוף התגובה מ-batchGet.

גוף הבקשה

כדי להשתמש ב-Analytics Reporting API v4 כדי לבקש נתונים, עליך ליצור אובייקט ReportRequest, שמכיל את הדרישות המינימליות הבאות:

  • מזהה חוקי של תצוגה מפורטת לשדה viewId.
  • לפחות ערך חוקי אחד בשדה dateRanges.
  • לפחות רשומה חוקית אחת בשדה metrics.

כדי לאתר מזהה תצוגה מפורטת, אפשר להריץ שאילתה על השיטה סיכומי החשבון או להשתמש ב-Account Explorer. אם לא ציינת טווח תאריכים, טווח התאריכים המוגדר כברירת מחדל הוא: {"startDate": "7daysAgo", "endDate": "yesterday"}.

הנה בקשה לדוגמה עם שדות החובה המינימליים:

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

השיטה batchGet מקבלת עד חמישה אובייקטים מסוג ReportRequest. כל הבקשות צריכות לכלול את אותם מאפייני dateRange, viewId, segments, samplingLevel וcohortGroup.

גוף התשובה

גוף התגובה לבקשת ה-API הוא מערך של אובייקטים מסוג Report. מבנה הדוח מוגדר באובייקט ColumnHeader שמתאר את המאפיינים והמדדים ואת סוגי הנתונים שלהם בדוח. ערכי המאפיינים והמדדים מצוינים בשדה data.

הנה דוגמה לתגובה לבקשה לדוגמה שלמעלה:

{
    "reports": [
        {
            "columnHeader": {
                "metricHeader": {
                    "metricHeaderEntries": [
                        {
                            "name": "ga:users",
                            "type": "INTEGER"
                        }
                    ]
                }
            },
            "data": {
                "isDataGolden": true,
                "maximums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "minimums": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ],
                "rowCount": 1,
                "rows": [
                    {
                        "metrics": [
                            {
                                "values": [
                                    "98"
                                ]
                            }
                        ]
                    }
                ],
                "totals": [
                    {
                        "values": [
                            "98"
                        ]
                    }
                ]
            }
        }
    ]
}

מדדים

מדדים הם אומדנים כמותיים. לכל בקשה נדרש לפחות אובייקט Metric אחד.

בדוגמה הבאה, המדד Sessions מסופק לשיטה batchGet כדי לקבל את המספר הכולל של סשנים בטווח התאריכים שצוין:

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

תוכל להשתמש בסייר המאפיינים והמדדים או ב-Metadata API כדי לקבל את רשימת המאפיינים והמדדים הזמינים.

סינון

כששולחים בקשה batchGet, אפשר לבקש ממנה להחזיר רק מדדים שעומדים בקריטריונים ספציפיים. כדי לסנן מדדים, בגוף הבקשה צריך לציין MetricFilterClauses אחד או יותר ובכל MetricFilterClause מגדירים MetricFilters אחד או יותר. בכל MetricFilter, צריך לציין את הערכים הבאים:

  • metricName
  • not
  • operator
  • comparisonValue

הפונקציה {metricName} מייצגת את המדד, {operator} את operator ואת {comparisonValue} ה-comparisonValue. לאחר מכן המסנן פועל באופן הבא:

if {metricName} {operator} {comparisonValue}
   return the metric

אם מציינים את הערך true עבור not, המסנן פועל באופן הבא:

if {metricName} {operator} {comparisonValue}
   do not return the metric

בדוגמה הבאה, batchGet מחזיר רק צפיות בדף שהערך שלהן גדול מ-2:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "metricFilterClauses": [{
          "filters": [{
              "metricName": "ga:pageviews",
              "operator": "GREATER_THAN",
              "comparisonValue": "2"
          }]
      }]
  }]
}

ביטויים

ביטוי של מדד הוא ביטוי מתמטי שמגדירים במדדים קיימים. הוא פועל כמו מדדים מחושבים דינמיים. אפשר להגדיר כינוי לייצוג ביטוי המדד, לדוגמה:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {
          "expression": "ga:goal1completions/ga:users",
          "alias": "completions per user"
        }
      ]
    }
  ]
}

סידור הסרטונים

כדי למיין את התוצאות לפי ערך של מדד:

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

בדוגמה הבאה, batchGet מחזירה את המדדים שממוינים תחילה לפי ביקורים ולאחר מכן לפי צפיות בדף בסדר יורד:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics":
      [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "orderBys":
      [
        {"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
        {"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
      ]
    }
  ]
}

מאפיינים

המאפיינים מתארים מאפיינים של המשתמשים שלך, הפעילויות שלהם באתר והפעולות שהם נקטו. לדוגמה, המאפיין 'עיר' מתאר מאפיין של פעילויות באתר ומציין את העיר ('פריז' או 'ניו יורק') שממנה הגיעה כל פעילות באתר. בבקשת batchGet, ניתן לציין אפס אובייקטים של מאפיין או יותר, לדוגמה:

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

סינון

כששולחים בקשה batchGet, אפשר לבקש ממנה להחזיר רק מאפיינים שעומדים בקריטריונים ספציפיים. כדי לסנן מאפיינים, בגוף הבקשה מציינים DimensionsFilterClauses אחד או יותר ובכל DimensionsFilterClause מגדירים DimensionsFilters אחד או יותר. בכל DimensionsFilters, צריך לציין את הערכים הבאים:

  • dimensionName
  • not
  • operator
  • expressions
  • caseSensitive

הפונקציה {dimensionName} מייצגת את המאפיין, {operator} את operator ו-{expressions} את expressions. לאחר מכן המסנן פועל באופן הבא:

if {dimensionName} {operator} {expressions}
    return the dimension

אם מציינים את הערך true עבור not, המסנן פועל באופן הבא:

if {dimensionName} {operator} {expressions}
    do not return the dimension

בדוגמה הבאה, batchGet מחזיר צפיות בדפים וסשנים בדפדפן Chrome:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"endDate": "2014-11-30", "startDate": "2014-11-01"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
      "dimensionFilterClauses": [
        {
          "filters": [
            {
              "dimensionName": "ga:browser",
              "operator": "EXACT",
              "expressions": ["Chrome"]
            }
          ]
        }
      ]
    }
  ]
}

סידור הסרטונים

כדי למיין את התוצאות לפי ערך של מאפיין:

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

לדוגמה, השדה batchGet הבא מחזיר את המאפיינים שממוינים לפי מדינה ואז לפי דפדפן:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
      "orderBys": [
        {"fieldName": "ga:country"},
        {"fieldName": "ga:browser"}
      ]
    }
  ]
}

קטגוריות היסטוגרמה

למאפיינים עם ערכים במספרים שלמים, קל יותר להבין את המאפיינים שלהם על ידי סיווג הערכים שלהם לטווחים. משתמשים בשדה histogramBuckets כדי להגדיר את הטווחים של הקטגוריות המתקבלות, ולציין את HISTOGRAM_BUCKET כסוג ההזמנה. לדוגמה:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "metrics": [{"expression": "ga:sessions"}],
      "dimensions": [
        {
          "name": "ga:sessionCount",
          "histogramBuckets": ["1","10","100","200","400"]
        }
      ],
      "orderBys": [
        {
          "fieldName": "ga:sessionCount",
          "orderType": "HISTOGRAM_BUCKET"
        }
      ]
    }
  ]
}

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

ב-Google Analytics Reporting API v4 אפשר לקבל נתונים בכמה טווחי תאריכים בבקשה אחת. אם הבקשה מציינת טווח תאריכים אחד או שניים, הנתונים מוחזרים באובייקט dateRangeValue, לדוגמה:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}]
    }
  ]
}

הזמנת דלתא

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

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges": [
        {"startDate": "2014-11-01", "endDate": "2014-11-30"},
        {"startDate": "2014-10-01", "endDate": "2014-10-30"}
      ],
      "metrics": [
        {"expression": "ga:pageviews"},
        {"expression": "ga:sessions"}
      ],
      "dimensions": [{"name": "ga:pageTitle"}],
      "orderBys": [
        {
          "fieldName": "ga:sessions",
          "orderType": "DELTA"
        }
      ]
    }
  ]
}

התנהגות המאפיין 'תאריך'

אם מבקשים מאפיין שקשור ל-תאריך או שעה, האובייקט DateRangeValue יכיל רק ערכים של תאריכים שנמצאים בטווחים התואמים. כל שאר הערכים שאינם בטווחי התאריכים שצוינו יהיו 0.

לדוגמה, נניח בקשה למאפיין ga:date ולמדד ga:sessions בשני טווחי תאריכים: ינואר ופברואר. בתגובה לנתונים המבוקשים בינואר, הערכים בפברואר יהיו 0, ובתגובה לנתונים המבוקשים בפברואר, הערכים בינואר יהיו 0.

דוח לחודש ינואר

{
    "dimensions": [
        "20140101" # `ga:date` dimension value for January 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "8"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "0"
            ]
        }
    ]
},
...

דוח לחודש פברואר

{
    "dimensions": [
        "20140201"  # `ga:date` dimension value for February 1, 2014.
    ],
    "metrics": [
        {
            "values": [ # January DateRangeValue.
                "0"
            ]
        },
        {
            "values": [ # February DateRangeValue.
                "7"
            ]
        }
    ]
},
...

פלחים

על מנת לבקש קבוצת משנה של הנתונים ב-Analytics, צריך להשתמש בפלחים. לדוגמה, ניתן לך להגדיר משתמשים ממדינה או מעיר מסוימת בפלח אחד, ומשתמשים שביקרו בחלק ספציפי של האתר בפלח אחר. המסננים מחזירים רק שורות שעומדות בתנאי, ואילו הפלחים מחזירים קבוצת משנה של משתמשים, סשנים או אירועים שעומדים בתנאים שמכילים את הפלחים.

כששולחים בקשה באמצעות פלחים, צריך לוודא את הפרטים הבאים:

  • כל ReportRequest בשיטת batchGet חייב להכיל הגדרות פלחים זהות.
  • מוסיפים את ga:segment לרשימת המאפיינים.

למשל:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests": [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
      "metrics": [{"expression": "ga:sessions"}],
      "segments": [
        {
          "dynamicSegment":
          {
            "name": "Sessions with Safari browser",
            "userSegment":
            {
              "segmentFilters": [
                {
                  "simpleSegment":
                  {
                    "orFiltersForSegment": [
                      {
                        "segmentFilterClauses": [
                          {
                            "dimensionFilter":
                            {
                              "dimensionName": "ga:browser",
                              "operator": "EXACT",
                              "expressions": ["Safari"]
                            }
                        }]
                    }]
                  }
              }]
            }
          }
      }]
  }]
}

בקטע טעימות תוכלו לראות עוד בקשות לדוגמה עם פלחים.

מזהה הפלח

משתמשים בשדה segmentId כדי לבקש פלחים. לא ניתן להשתמש גם ב-segmentId וגם ב-dynamicSegment כדי לבקש פלחים.

למשל:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
      "metrics": [{"expression": "ga:users"}],
      "segments":  [{"segmentId": "gaid::-3"}]
    }
  ]
}

דגימות

דגימה יכולה להשפיע על תוצאות הנתונים, וזו סיבה נפוצה לכך שהערכים שמוחזרים מה-API לא תואמים לממשק האינטרנט. משתמשים בשדה samplingLevel כדי להגדיר את גודל הדגימה הרצוי.

  • כדי לקבל תגובה מהירה עם דגימה קטנה יותר, צריך להגדיר את הערך SMALL.
  • יש להגדיר את הערך כ-LARGE לתגובה מדויקת יותר אבל איטית יותר.
  • צריך להגדיר את הערך DEFAULT בתגובה ששומרת על איזון בין המהירות לדיוק.

למשל:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions": [{"name": "ga:medium"}],
      "metrics": [{"expression": "ga:sessions"}],
      "samplingLevel":  "LARGE"
    }
  ]
}

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

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

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

חלוקה לדפים

ב-Analytics Reporting API v4, המערכת משתמשת בשדות pageToken ו-pageSize כדי לעבור לדפים עם תוצאות תשובות שמתפרשות על פני מספר דפים. מקבלים pageToken מהפרמטר nextPageToken בתגובה לבקשה של reports.batchGet:

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

השלב הבא

אחרי שהסברתם את העקרונות הבסיסיים של יצירת דוח, נציג את התכונות המתקדמות של API v4.