يتيح لك الإصدار 1 من Google Analytics Data API إنشاء جداول محورية. الجداول المحورية هي أداة لتلخيص البيانات تصور البيانات عن طريق إعادة ترتيب المعلومات في الجدول من خلال تحريك البيانات (تدوير) البيانات على بُعد واحد أو عدة بعد.

كمثال، ضع في الاعتبار جدول البيانات الأولية التالي:

باستخدام هذه البيانات، يمكن إنشاء جدول محوري، وتقسيم بيانات الجلسات حسب المتصفّح، مع اختيار أبعاد البلد واللغة كنقاط محورية إضافية.

الميزات المشتركة مع التقارير الأساسية

تتضمّن طلبات إعداد التقارير المحورية الدلالات نفسها مع طلبات التقارير الأساسية للعديد من الميزات المشتركة. على سبيل المثال، التقسيم على صفحات وفلاتر السمات وخصائص المستخدمين يتصرفون بالطريقة نفسها في "التقارير المحورية" مثل "التقارير الأساسية". يركز هذا الدليل على ميزات إعداد التقارير المحورية. للتعرّف على وظيفة "التقارير الأساسية" للإصدار 1 من Data API، يُرجى قراءة دليل أساسيات إعداد التقارير ودليل حالات الاستخدام المتقدّمة.

طرق إعداد التقارير المحورية

يدعم الإصدار الأول من Data API الوظائف المحورية في طرق إعداد التقارير التالية:

• runPivotReport هذه الطريقة تعرض تقريرًا محوريًا مخصّصًا لبيانات أحداثك في "إحصاءات Google". يصف كل محوري أعمدة وصفوف السمات المرئية في استجابة التقرير.

• batchRunPivotReports هو إصدار مجمّع من طريقة runPivotReport التي تتيح إنشاء تقارير متعددة باستخدام طلب واحد من واجهة برمجة التطبيقات.

اختيار كيان لإعداد التقارير

تتطلّب جميع طرق الإصدار 1 من Data API تحديد معرّف الموقع على "إحصاءات Google 4" داخل مسار طلب عنوان URL على شكل properties/GA4_PROPERTY_ID، مثل:

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

سيتم إنشاء التقرير الناتج استنادًا إلى بيانات أحداث "إحصاءات Google" التي يتمّ جمعها في موقع "إحصاءات Google 4" المحدّد.

وإذا كنت تستخدم إحدى مكتبات برامج واجهة برمجة التطبيقات للبيانات، لن يكون هناك داعٍ لمعالجة مسار عنوان URL للطلب يدويًا. توفّر معظم برامج واجهات برمجة التطبيقات مَعلمة property التي تتوقع سلسلة على شكل properties/GA4_PROPERTY_ID. راجِع دليل البدء السريع للاطّلاع على أمثلة على استخدام مكتبات العملاء.

طلب تقرير محوري

لإنشاء طلب باستخدام جدول محوري، استخدِم طريقة runPivotReport أو طريقة batchRunPivotReports.

لطلب البيانات المحورية، يمكنك إنشاء كائن RunPivotReportRequest. نوصي بالبدء بمعلمات الطلب التالية:

• إدخال صالح في الحقل dateRanges.
• إدخال واحد صالح على الأقل في حقل السمات
• إدخال واحد صالح على الأقل في حقل metrics
• إدخالان محوريان صالحان على الأقل في حقل المحوري

إليك نموذج طلب يتضمّن الحقول المقترَحة:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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 أعمدة وصفوف السمات المرئية في استجابة التقرير.

يتيح الإصدار 1 من Data API استخدام عدة عروض محورية ما دام ناتج معلَمة الحدّ الأقصى لكلّ محور معيّن لا يتجاوز 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
      }
    ],

المقاييس

المقاييس هي مقاييس كمّية لبيانات الأحداث الخاصة بموقعك الإلكتروني أو تطبيقك. وفي طلب التقرير، يمكنك تحديد مقياس واحد أو أكثر. اطّلِع على مقاييس واجهة برمجة التطبيقات للحصول على قائمة كاملة بأسماء مقاييس واجهة برمجة التطبيقات المتاحة ليتم تحديدها في الطلبات.

في طلبات التقارير المحورية، يتم تحديد المقاييس باستخدام الحقل 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"
        }
      ]
    },
  ....

  }

تقسيم النتائج على عدّة صفحات

على غرار طرق إعداد التقارير الأساسية، تسمح لك طلبات المحتوى المحوري بتحديد حقلَي الحدّ الأقصى والإزاحة في العنصر المحوري لتنفيذ عملية التقسيم على صفحات. يتم تطبيق إعدادات التقسيم على صفحات على كل محوري على حدة. يجب ملء الحقل limit لكل عنصر Pivot من أجل الحدّ من عدد القيم الفريدة للسمة في التقرير.

يتيح الإصدار الأول من 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
          }
        ]
      }

الردّ على التقرير

تكون استجابة التقرير المحوري لطلب البيانات من واجهة برمجة التطبيقات المحورية عنوانًا وصفوفًا بشكل أساسي.

عناوين الاستجابة

يتكوّن عنوان التقرير المحوري من 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"
        }
      ]
    },
    ...

  ]

تتجاوب هذه البيانات مع الخليتين المميزتين في الجدول أدناه:

مكتبات العملاء

راجِع دليل البدء السريع للحصول على شرح حول كيفية تثبيت مكتبات العملاء وضبطها.

في ما يلي مثال على استخدام مكتبة عملاء 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)

run_pivot_report.py

تطبيق تجريبي

اطّلِع على تطبيق العرض التوضيحي لتقرير محور الإصدار 1 من Google Analytics API للحصول على مثال عن كيفية إنشاء تقرير محوري باستخدام JavaScript وعرضه.