סקירה כללית

Google Analytics Data API v1 מאפשר ליצור טבלאות צירים. מגביה כידון Pivot טבלאות הן כלי לסיכום נתונים שממחיש באופן חזותי את הנתונים על ידי סידור מחדש של הנתונים בטבלה על ידי הצגת הנתונים בסבב (סבב) מאפיינים.

כדוגמה, נבחן את טבלת הנתונים הגולמיים הבאה:

טבלת נתונים גולמיים

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

טבלת נתונים עם צירים

תכונות משותפות עם דוחות ליבה

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

שיטות דיווח על צירים

Data API v1 תומך בפונקציונליות של צירים בשיטות הדיווח הבאות:

  • runPivotReport בשיטה הזו מחזירה דוח צירים בהתאמה אישית של נתוני האירוע ב-Google Analytics. כל אחד בצירופים מתוארים העמודות והשורות של המאפיינים הגלויים בתגובת הדוח.

  • batchRunPivotReports היא גרסת אצווה של ה-method runPivotReport שמאפשרת ליצור דוחות מרובים באמצעות קריאה אחת ל-API.

בחירת ישות מדווחת

לכל השיטות ב-Data API v1 נדרש מזהה הנכס של Google Analytics יצוין בתוך נתיב בקשה של כתובת URL, properties/GA_PROPERTY_ID, למשל:

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport

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

אם אתם משתמשים באחת מספריות הלקוח של Data API, אין צורך לשנות באופן ידני את נתיב כתובת ה-URL של הבקשה. רוב לקוחות API מספקים פרמטר property שמצפה למחרוזת בצורת properties/GA_PROPERTY_ID. לעיון במדריך למתחילים כדי לקבל דוגמאות לשימוש בספריות הלקוח.

בקשה לדוח צירים

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

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

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

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

HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
  {
    "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
    "dimensions": [
        { "name": "browser" },
        { "name": "country" },
        { "name": "language" }
      ],
    "metrics": [{ "name": "sessions" }],
    "pivots": [
      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5
      },
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250
      },
      {
        "fieldNames": [
          "language"
        ],
        "limit": 15
      }
    ]
  }

צירים

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

Data API v1 תומך במספר צירים כל עוד המכפלה של המגבלה לכל ציר לא עולה על 100,000.

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

    "pivots": [
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250,
        "orderBys": [
          {
            "dimension": {
              "dimensionName": "country"
            }
          }
        ]
      },
      {
        "fieldNames": [
          "browser"
        ],
        "offset": 3,
        "limit": 3,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      }
    ],
    ...

מידות

מאפיינים מתארים ומקבצים נתוני אירועים עבור באתר או באפליקציה. לדוגמה, המאפיין city מציין את העיר ("פריז" או 'תל אביב') שממנו הגיע כל אירוע. בבקשת הדיווח, אפשר לציין אפס מאפיינים או יותר.

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

בהמשך מופיע קטע קוד שמדגים את השימוש בשדות dimension ו-fieldNames לטבלה עם צירים מסוג browser, country ו-language:

    "pivots": [
      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      },
      {
        "fieldNames": [
          "country"
        ],
        "limit": 250,
        "orderBys": [
          {
            "dimension": {
              "dimensionName": "country"
            }
          }
        ]
      },
      {
        "fieldNames": [
          "language"
        ],
        "limit": 10
      }
    ],

מדדים

מדדים הם מדידות כמותיות של נתוני אירועים באתר או באפליקציה. בבקשת דוח, אפשר לציין מדד אחד או יותר. רשימה מלאה של שמות מדדי ה-API מופיעה במדדי ה-API. שאפשר לציין אותן בבקשות.

בבקשות לדוחות צירים, המדדים מוגדרים באמצעות השדה metrics, גוף הבקשה, שדומה לשיטות דיווח ליבה.

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

    "metrics": [
      {
        "name": "sessions"
      }
    ],

צבירת מדדים

משתמשים בmetricAggregations של אובייקט ציר לחישוב מדד מצטבר בכל ציר.

צבירת הנתונים יחושבו רק אם metricAggregations השדה מצוין בבקשה.

בהמשך מופיע קטע של שאילתה שמבקשת את הסכומים הכוללים עבור מאפיין ציר browser:

"pivots": [
  {
    "fieldNames": [
      "browser"
    ],
    "limit": 10,
    "metricAggregations": [
      "TOTAL",
    ]
  },
  ...

המדדים המחושבים מוחזרים בקטע צבירת נתונים השדה RunPivotReportResponse לאובייקט. בשורות של מדדים מצטברים, השדה dimensionValues מכיל ערך מיוחד של RESERVED_TOTAL, RESERVED_MAX או RESERVED_MIN.

  "aggregates": [
    {
      "dimensionValues": [
        {
          "value": "Chrome"
        },
        {
          "value": "RESERVED_TOTAL"
        },
        {
          "value": "RESERVED_TOTAL"
        }
      ],
      "metricValues": [
        {
          "value": "4"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Firefox"
        },
        {
          "value": "RESERVED_TOTAL"
        },
        {
          "value": "RESERVED_TOTAL"
        }
      ],
      "metricValues": [
        {
          "value": "6"
        }
      ]
    },
  ....

  }

חלוקה לדפים

בדומה לשיטות דיווח ליבה, בקשות צירים מאפשרות לך כדי לציין את המגבלה ו-offset משדות אובייקט Pivot כדי להטמיע עימוד. הגדרות העימוד חלות על כל ציר בנפרד. השדה limit חובה לכל אובייקט Pivot כדי להגביל את של העוצמה (cardinality).

Data API v1 תומך במספר צירים כל עוד המוצר של limit לכל ציר לא עולה על 100,000.

בהמשך מופיע קטע קוד שמדגים את השימוש בשדות offset ו-limit כדי מאחזרים את חמשת המאפיינים הבאים של language עם היסט של 10:

      {
        "fieldNames": [
          "language"
        ],
        "offset": 10,
        "limit": 5
      }

סינון

בדומה לפונקציונליות הדיווח הבסיסית, מסנן מאפיינים ברמת הבקשה צריך להשתמש בהן אם רוצים לסנן מאפיינים בדוח צירים בקשה.

מיון

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

כל OrderBy יכול להכיל אחת מהאפשרויות הבאות:

בדוגמה זו מוצג קטע קוד להגדרת ציר שמבסס את הדוח על המאפיין browser, סידור התוצאות לפי המדד sessions ב סדר יורד.

      {
        "fieldNames": [
          "browser"
        ],
        "limit": 5,
        "orderBys": [
          {
            "metric": {
              "metricName": "sessions"
            },
            "desc": true
          }
        ]
      }

דיווח על התשובה

התגובה של דוח צירים של ציר בקשת ה-API של הדוח היא בעיקר כותרת ושורות.

כותרות של תשובות

הכותרת של דוח הצירים מורכבת מ-PivotHeaders, DimensionHeaders ו-MetricHeaders שמפרט את העמודות בטבלת צירים.

לדוגמה, דוח עם מאפייני ציר browser, country ו-language והמדד sessions יניב כותרות כמו:

{
  "pivotHeaders": [
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "Chrome"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Firefox"
            }
          ]
        },
        ...

      ],
      ...
    },
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "United States"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Canada"
            }
          ]
        },
        ...

      ],
      ...
    },
    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "English"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "French"
            }
          ]
        },
        ...

      ],
      ...
    }
  ],
  "dimensionHeaders": [
    {
      "name": "browser"
    },
    {
      "name": "country"
    },
    {
      "name": "language"
    }
  ],
  "metricHeaders": [
    {
      "name": "sessions",
      "type": "TYPE_INTEGER"
    }
  ],
  ...

}

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

טבלת נתונים גולמיים

שורות תגובה

תגובת דוח הצירים של runPivotReport ו-batchRunPivotReports השיטות שונות מהתשובה של שיטות הדיווח המרכזיות כמו runReport, ו-batchRunReports כל שורת תגובה של דוח צירים מייצגת תא יחיד טבלה, ואילו בדוח רגיל, שורת תשובה יחידה מייצגת בשורה בטבלה.

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

  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Chrome"
        },
        {
          "value": "United States"
        },
        {
          "value": "English"
        }
      ],
      "metricValues": [
        {
          "value": "1"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Firefox"
        },
        {
          "value": "Canada"
        },
        {
          "value": "French"
        }
      ],
      "metricValues": [
        {
          "value": "3"
        }
      ]
    },
    ...

  ]

הנתונים האלה תואמים לשני התאים שמודגשים בטבלה הבאה:

טבלת נתונים גולמיים

ספריות לקוח

ניתן למצוא הסבר במדריך למתחילים איך להתקין ולהגדיר ספריות לקוח.

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

PHP

use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient;
use Google\Analytics\Data\V1beta\DateRange;
use Google\Analytics\Data\V1beta\Dimension;
use Google\Analytics\Data\V1beta\Metric;
use Google\Analytics\Data\V1beta\OrderBy;
use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy;
use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy;
use Google\Analytics\Data\V1beta\Pivot;
use Google\Analytics\Data\V1beta\RunPivotReportRequest;
use Google\Analytics\Data\V1beta\RunPivotReportResponse;

/**
 * Runs a pivot query to build a report of session counts by country,
 * pivoted by the browser dimension.
 * @param string $propertyId Your GA-4 Property ID
 */
function run_pivot_report(string $propertyId)
{
    // Create an instance of the Google Analytics Data API client library.
    $client = new BetaAnalyticsDataClient();

    // Make an API call.
    $request = (new RunPivotReportRequest())
        ->setProperty('properties/' . $propertyId)
        ->setDateRanges([new DateRange([
            'start_date' => '2021-01-01',
            'end_date' => '2021-01-30',
            ]),
        ])
        ->setPivots([
            new Pivot([
                'field_names' => ['country'],
                'limit' => 250,
                'order_bys' => [new OrderBy([
                    'dimension' => new DimensionOrderBy([
                        'dimension_name' => 'country',
                    ]),
                ])],
            ]),
            new Pivot([
                'field_names' => ['browser'],
                'offset' => 3,
                'limit' => 3,
                'order_bys' => [new OrderBy([
                    'metric' => new MetricOrderBy([
                        'metric_name' => 'sessions',
                    ]),
                    'desc' => true,
                ])],
            ]),
        ])
        ->setMetrics([new Metric(['name' => 'sessions'])])
        ->setDimensions([
            new Dimension(['name' => 'country']),
            new Dimension(['name' => 'browser']),
        ]);
    $response = $client->runPivotReport($request);

    printPivotReportResponse($response);
}

/**
 * Print results of a runPivotReport call.
 * @param RunPivotReportResponse $response
 */
function printPivotReportResponse(RunPivotReportResponse $response)
{
    print 'Report result: ' . PHP_EOL;

    foreach ($response->getRows() as $row) {
        printf(
            '%s %s' . PHP_EOL,
            $row->getDimensionValues()[0]->getValue(),
            $row->getMetricValues()[0]->getValue()
        );
    }
}

Python

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
    DateRange,
    Dimension,
    Metric,
    OrderBy,
    Pivot,
    RunPivotReportRequest,
)


def run_sample():
    """Runs the sample."""
    # TODO(developer): Replace this variable with your Google Analytics 4
    #  property ID before running the sample.
    property_id = "YOUR-GA4-PROPERTY-ID"
    run_pivot_report(property_id)


def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
    """Runs a pivot query to build a report of session counts by country,
    pivoted by the browser dimension."""
    client = BetaAnalyticsDataClient()

    request = RunPivotReportRequest(
        property=f"properties/{property_id}",
        date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
        pivots=[
            Pivot(
                field_names=["country"],
                limit=250,
                order_bys=[
                    OrderBy(
                        dimension=OrderBy.DimensionOrderBy(dimension_name="country")
                    )
                ],
            ),
            Pivot(
                field_names=["browser"],
                offset=3,
                limit=3,
                order_bys=[
                    OrderBy(
                        metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
                    )
                ],
            ),
        ],
        metrics=[Metric(name="sessions")],
        dimensions=[Dimension(name="country"), Dimension(name="browser")],
    )
    response = client.run_pivot_report(request)
    print_run_pivot_report_response(response)


def print_run_pivot_report_response(response):
    """Prints results of a runPivotReport call."""
    print("Report result:")
    for row in response.rows:
        for dimension_value in row.dimension_values:
            print(dimension_value.value)

        for metric_value in row.metric_values:
            print(metric_value.value)


Node.js

  // TODO(developer): Uncomment this variable and replace with your
  // Google Analytics 4 property ID before running the sample.
  // propertyId = Y'OUR-GA4-PROPERTY-ID;'

  // Imports the Google Analytics Data API client library.
  const {BetaAnalyticsDataClient} = require(@'google-analytics/data)';

  // Initialize client that will be used to send requests. This client only
  // needs to be created once, and can be reused for multiple requests.
  const analyticsDataClient = new BetaAnalyticsDataClient();

  // Runs a pivot query to build a report of session counts by country, pivoted by the browser dimension.
  async function runPivotReport() {
    const [response] = await analyticsDataClient.runPivotReport({
      property: `properties/${propertyId}`,
      dateRanges: [
        {
          startDate: 2'021-01-01,'
          endDate: 2'021-01-30,'
        },
      ],
      pivots: [
        {
          fieldNames: [c'ountry]',
          limit: 250,
          orderBys: [
            {
              dimension: {
                dimensionName: c'ountry,'
              },
            },
          ],
        },
        {
          fieldNames: [b'rowser]',
          offset: 3,
          limit: 3,
          orderBys: [
            {
              metric: {
                metricName: s'essions,'
              },
              desc: true,
            },
          ],
        },
      ],
      metrics: [
        {
          name: s'essions,'
        },
      ],
      dimensions: [
        {
          name: c'ountry,'
        },
        {
          name: b'rowser,'
        },
      ],
    });
    printPivotReportResponse(response);
  }

  runPivotReport();

  // Prints results of a runReport call.
  function printPivotReportResponse(response) {
    console.log(R'eport result:)';
    response.rows.forEach(row = >{
      row.dimensionValues.forEach(dimensionValue = >{
        console.log(dimensionValue.value);
      });

      row.metricValues.forEach(metricValue = >{
        console.log(metricValue.value);
      });
    });
  }r

בקשה להדגמה (דמו)

לצפייה בהדגמה של דוח הצירים של Google Analytics API v1 אפליקציה דוגמה לאופן שבו אפשר לבנות ולהציג דוח צירים באמצעות JavaScript.