יצירת דוח

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

דוחות

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

גוף הבקשה

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

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

כדי לאתר view ID, צריך לבצע שאילתה על השיטה סיכומי החשבון או להשתמש ב-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 מסופק ל-method 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.