Method: properties.runReport

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

لدليل إنشاء الطلبات وفهم الردود، يُرجى الاطّلاع على إنشاء تقرير.

طلب HTTP

POST https://analyticsdata.googleapis.com/v1beta/{property=properties/*}:runReport

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

مَعلمات المسار

المعلمات
property

string

معرّف موقع على "إحصاءات Google 4" يتم تتبُّع أحداثه. يتم تحديده في مسار عنوان URL وليس في النص الأساسي لمزيد من المعلومات، اطّلِع على مكان العثور على رقم تعريف الموقع. ضمن الطلب المجمّع، يجب أن تكون هذه السمة غير محدّدة أو متوافقة مع الموقع على مستوى الدفعة.

مثال: المواقع الإلكترونية/1234

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "dimensions": [
    {
      object (Dimension)
    }
  ],
  "metrics": [
    {
      object (Metric)
    }
  ],
  "dateRanges": [
    {
      object (DateRange)
    }
  ],
  "dimensionFilter": {
    object (FilterExpression)
  },
  "metricFilter": {
    object (FilterExpression)
  },
  "offset": string,
  "limit": string,
  "metricAggregations": [
    enum (MetricAggregation)
  ],
  "orderBys": [
    {
      object (OrderBy)
    }
  ],
  "currencyCode": string,
  "cohortSpec": {
    object (CohortSpec)
  },
  "keepEmptyRows": boolean,
  "returnPropertyQuota": boolean,
  "comparisons": [
    {
      object (Comparison)
    }
  ]
}
الحقول
dimensions[]

object (Dimension)

السمات المطلوبة وعرضها
metrics[]

object (Metric)

المقاييس المطلوبة والمعروضة
dateRanges[]

object (DateRange)

النطاقات الزمنية للبيانات المطلوب قراءتها في حال طلب نطاقات زمنية متعددة، سيحتوي كل صف استجابة على فهرس نطاق زمني يستند إلى صفر. وفي حال تداخل نطاقَين زمنيَين، يتم تضمين بيانات الأحداث للأيام المتداخلة في صفوف الردود لكلا النطاقَين الزمنيَين. في طلب المجموعة النموذجية، يجب عدم تحديد قيمة dateRanges هذه.
dimensionFilter

object (FilterExpression)

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

object (FilterExpression)

عبارة تصفية المقاييس. يتم تطبيقها بعد تجميع صفوف التقرير، على غرار لغة SQL التي تحتوي على عبارة. لا يمكن استخدام الأبعاد في هذا الفلتر.
offset

string (int64 format)

عدد صفوف صف البداية. يتم احتساب الصف الأول على أنه الصف 0.

عند الترحيل، لا يحدد الطلب الأول الإزاحة؛ أو ما يعادل ذلك، يتم تعيينها على 0؛ يعرض الطلب الأول أول limit من الصفوف. ويحدّد الطلب الثاني معادلة لقيمة limit للطلب الأول، فإن الطلب الثاني يُرجع limit الثانية من الصفوف.

لمزيد من المعلومات عن مَعلمة تقسيم النتائج على صفحات، يمكنك الاطّلاع على مقالة التقسيم على صفحات.
limit

string (int64 format)

عدد الصفوف المطلوب عرضها. في حال عدم تحديد قيمة هذا الحقل، سيتم عرض 10,000 صف. تعرض واجهة برمجة التطبيقات 250,000 صف كحدٍ أقصى لكل طلب، بغض النظر عن عدد الصفوف التي تطلبها. يجب أن تكون قيمة limit موجبة.

ويمكن أن تعرض واجهة برمجة التطبيقات أيضًا صفوفًا أقل من قيمة limit المطلوبة، إذا لم يتوفّر عدد قيم السمات مثل limit. على سبيل المثال، هناك أقل من 300 قيمة محتملة للسمة country؛ وبالتالي عند إعداد التقارير عن country فقط، لا يمكنك الحصول على أكثر من 300 صف، حتى في حال إعداد limit على قيمة أعلى.

لمزيد من المعلومات عن مَعلمة تقسيم النتائج على صفحات، يمكنك الاطّلاع على مقالة التقسيم على صفحات.
metricAggregations[]

enum (MetricAggregation)

تجميع المقاييس. ستظهر قيم المقاييس المجمّعة في صفوف تم فيها ضبط قيم السمة على RESERVED_(MetricAggregation)".
orderBys[]

object (OrderBy)

لتحديد كيفية ترتيب الصفوف في الردّ.
currencyCode

string

رمز عملة بتنسيق ISO4217، مثل "AED" و"USD" و"JPY". إذا كان الحقل فارغًا، يستخدِم التقرير العملة التلقائية للموقع.
cohortSpec

object (CohortSpec)

المجموعة النموذجية المرتبطة بهذا الطلب. إذا كانت هناك مجموعة نموذجية في الطلب، تحتوي "المجموعة النموذجية" أن يكون متوفرًا.
keepEmptyRows

boolean

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

بغض النظر عن إعداد keepEmptyRows هذا، يمكن فقط عرض البيانات التي سجّلها موقع "إحصاءات Google" (GA4) في التقارير.

على سبيل المثال، إذا لم يسجِّل أحد المواقع حدث purchase مطلقًا، لن يحتوي طلب البحث عن السمة eventName والمقياس eventCount على صف eventName: "purchase" وeventCount: 0.
returnPropertyQuota

boolean

تبديل ما إذا كان سيتم عرض الحالة الحالية لحصة هذا الموقع على "إحصاءات Google". يتم عرض الحصة في PropertyQuota.
comparisons[]

object (Comparison)

اختياريّ. ضبط إعدادات المقارنات المطلوبة وعرضها لا يتطلّب الطلب سوى حقل مقارنات لكي يتلقّى عمود مقارنة في الردّ.

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال RunReportResponse.

نطاقات الأذونات

يتطلب هذا الإعداد أحد نطاقات OAuth التالية:

  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/analytics