כדאי לנסות את שרת ה-MCP של Google Analytics. אפשר להתקין את הכלי מ-GitHub, ולקרוא פרטים נוספים בהודעה.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

סקירה כללית

‫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 תומך בכמה טבלאות ציר, כל עוד המכפלה של הפרמטר limit בכל טבלת ציר לא חורגת מ-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 של גוף הבקשה, בדומה לשיטות של Core Reporting.

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

    "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"
        }
      ]
    },
  ....

  }

חלוקה לדפים

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

גרסה 1 של Data API תומכת בכמה טבלאות צירים, כל עוד המכפלה של הפרמטר limit בכל טבלת צירים לא חורגת מ-100,000.

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

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

סינון

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

מיון

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

כל OrderBy יכול להכיל אחד מהבאים:

‫DimensionOrderBy, ממיין את התוצאות לפי ערכי המאפיין.
‫MetricOrderBy, מיון התוצאות לפי ערכי המדד.
‫PivotOrderBy, משמש בשאילתות ציר וממיין את התוצאות לפי ערכי המדד בתוך קבוצת עמודות ציר.

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

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

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

התגובה Pivot Report Response לבקשת 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 שונה מתגובה של שיטות דיווח ב-Core Reporting, כמו 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.

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

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

שיטות דיווח על ציר זמן

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

בקשה לדוח ציר

HTTP

צירים

מידות

מדדים

צבירת נתונים של מדדים

חלוקה לדפים

סינון

מיון

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

כותרות תגובה

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

ספריות לקוח

PHP

Python

Node.js

אפליקציית הדגמה (דמו)

סקירה כללית