יצירת דוח

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

דוחות

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

גוף הבקשה

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

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

כדי לאתר מזהה תצוגה מפורטת, תוכלו להריץ שאילתות על השיטה סיכום חשבון או להשתמש בחשבון 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 המתאר את המאפיינים והמדדים ואת סוגי הנתונים שלהם בדוח. הערכים של המאפיינים והמדדים מצוינים בשדה נתונים.

לפניכם דוגמה לתגובה לבקשה לדוגמה:

{
    "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"
                        ]
                    }
                ]
            }
        }
    ]
}

מדדים

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

בדוגמה הבאה, המדד 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, אפשר לבקש ממנה להחזיר רק מדדים שעומדים בקריטריונים ספציפיים. כדי לסנן מדדים, בגוף הבקשה, צריך לציין MetricMetricClauses אחד או יותר, ובכל 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, אפשר לבקש ממנה להחזיר רק מאפיינים שעומדים בקריטריונים ספציפיים. כדי לסנן מאפיינים, בגוף הבקשה, מציינים מאפיין אחד או יותר dimensionFilterClauses, ובכל DimensionsFilterClause יש להגדיר מאפיין אחד או יותר FiltersFilters. בכל 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"
        }
      ]
    }
  ]
}

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

גרסה 4 של Google Analytics API מאפשרת לכם לקבל נתונים בכמה טווחי תאריכים בבקשה אחת. בין אם הבקשה מציינת טווח תאריכים אחד או שניים, הנתונים מוחזרים באובייקט 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"
    }
  ]
}

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

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

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

עימוד

שדה ה-API לדיווח בגרסה 4 של Analytics משתמש בשדות 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 גרסה 4.