סקירה כללית

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

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

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

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

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

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

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

שיטות דיווח של טבלאות צירים

גרסה 1 של Data API תומכת בפונקציית ציר בשיטות הדיווח הבאות:

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

  • ‫batchRunPivotReports זו גרסה של השיטה 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.
  • לפחות ערך תקין אחד בשדה dimensions.
  • לפחות ערך תקין אחד בשדה metrics.
  • לפחות שני ערכים תקפים של ציר בשדה 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 בגוף הבקשה. כל Pivot מתאר את העמודות והשורות של המאפיינים שמוצגים בתשובת הדוח.

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

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

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

מידות

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

צריך להגדיר את המאפיינים בשדה dimensions בגוף הבקשה. כדי שהמאפיינים האלה יוצגו בדוח, הם צריכים להופיע גם בשדה 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 של אובייקט Pivot כדי לחשב ערכים מצטברים של מדדים לכל ציר.

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

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

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

המדדים המחושבים מוחזרים בשדה aggregates של אובייקט 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"
        }
      ]
    },
  ....

  }

חלוקה לדפים

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

‫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

google-analytics-data/src/run_pivot_report.php
פתיחה ב-Cloud Shell הצגה ב-GitHub 
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()
        );
    }
}
run_pivot_report.php

Python

google-analytics-data/run_pivot_report.py
פתיחה ב-Cloud Shell הצגה ב-GitHub 
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)


run_pivot_report.py

Node.js

google-analytics-data/run_pivot_report.js
פתיחה ב-Cloud Shell הצגה ב-GitHub 
  // TODO(developer): Uncomment this variable and replace with your
  // Google Analytics 4 property ID before running the sample.
  // propertyId = 'YOUR-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: '2021-01-01',
          endDate: '2021-01-30',
        },
      ],
      pivots: [
        {
          fieldNames: ['country'],
          limit: 250,
          orderBys: [
            {
              dimension: {
                dimensionName: 'country',
              },
            },
          ],
        },
        {
          fieldNames: ['browser'],
          offset: 3,
          limit: 3,
          orderBys: [
            {
              metric: {
                metricName: 'sessions',
              },
              desc: true,
            },
          ],
        },
      ],
      metrics: [
        {
          name: 'sessions',
        },
      ],
      dimensions: [
        {
          name: 'country',
        },
        {
          name: 'browser',
        },
      ],
    });
    printPivotReportResponse(response);
  }

  runPivotReport();

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

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

אפליקציית הדגמה

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