Method: properties.runReport

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

طلب HTTP

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

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

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

المعلمات
property

string

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

مثال: properties/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)
    }
  ],
  "conversionSpec": {
    object (ConversionSpec)
  }
}
الحقول
dimensions[]

object (Dimension)

اختياريّ. السمات المطلوبة والمعروضة
metrics[]

object (Metric)

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

object (DateRange)

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

object (FilterExpression)

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

object (FilterExpression)

اختياريّ. عبارة الفلتر الخاصة بالمقاييس. يتم تطبيقها بعد تجميع صفوف التقرير، على غرار عبارة having في 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)

اختياريّ. تجميع المقاييس سيتم عرض قيم المقاييس المجمّعة في الصفوف التي تم ضبط dimensionValues فيها على "RESERVED_(MetricAggregation)". سيتم تجميع المقاييس التي تتضمّن كلاً من المقارنات والنطاقات الزمنية المتعددة استنادًا إلى النطاقات الزمنية.
orderBys[]

object (OrderBy)

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

string

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

object (CohortSpec)

اختياريّ. مجموعة المجموعة النموذجية المرتبطة بهذا الطلب. إذا كانت هناك مجموعة نموذجية في الطلب، يجب توفُّر السمة "المجموعة النموذجية".
keepEmptyRows

boolean

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

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

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

boolean

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

object (Comparison)

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

object (ConversionSpec)

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

نص الاستجابة

جدول تقرير الردود الذي يتوافق مع طلب معيّن

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "dimensionHeaders": [
    {
      object (DimensionHeader)
    }
  ],
  "metricHeaders": [
    {
      object (MetricHeader)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totals": [
    {
      object (Row)
    }
  ],
  "maximums": [
    {
      object (Row)
    }
  ],
  "minimums": [
    {
      object (Row)
    }
  ],
  "rowCount": integer,
  "metadata": {
    object (ResponseMetaData)
  },
  "propertyQuota": {
    object (PropertyQuota)
  },
  "kind": string,
  "nextPageToken": string
}
الحقول
dimensionHeaders[]

object (DimensionHeader)

تصف أعمدة السمات. يتطابق عدد DimensionHeaders وترتيبها مع السمات المتوفّرة في الصفوف.
metricHeaders[]

object (MetricHeader)

تصف هذه السمة أعمدة المقاييس. يتطابق عدد MetricHeaders وترتيبها مع المقاييس المتوفّرة في الصفوف.
rows[]

object (Row)

صفوف تتضمّن مجموعات من قيم السمات وقيم المقاييس في التقرير
totals[]

object (Row)

إذا طُلب ذلك، القيم الإجمالية للمقاييس
maximums[]

object (Row)

تمثّل هذه السمة الحد الأقصى لقيم المقاييس، إذا طُلب ذلك.
minimums[]

object (Row)

تمثّل هذه السمة الحد الأدنى لقيم المقاييس، إذا طُلب ذلك.
rowCount

integer

إجمالي عدد الصفوف في نتيجة طلب البحث، بغض النظر عن عدد الصفوف المعروضة في الردّ على سبيل المثال، إذا عرض طلب بحث 175 صفًا وتضمّن limit = 50 في طلب بيانات من واجهة برمجة التطبيقات، ستحتوي الاستجابة على rowCount = 175 ولكن 50 صفًا فقط.

لمزيد من المعلومات عن مَعلمة التقسيم إلى صفحات، اطّلِع على التقسيم إلى صفحات.
metadata

object (ResponseMetaData)

بيانات وصفية للتقرير
propertyQuota

object (PropertyQuota)

حالة الحصة لهذا الموقع على "إحصاءات Google"، بما في ذلك هذا الطلب
kind

string

تحدّد نوع المورد الذي تمثله هذه الرسالة. تكون قيمة kind دائمًا السلسلة الثابتة "analyticsData#runReport". يُستخدَم للتمييز بين أنواع الاستجابات في JSON.
nextPageToken

string

رمز مميز يمكن إرساله كـ pageToken لاسترداد الصفحة التالية. في حال حذف هذا الحقل، لن تكون هناك صفحات لاحقة.

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

يجب توفير أحد نطاقات OAuth التالية:

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

مقارنة

تحدّد هذه السمة مقارنة فردية. ستتضمّن معظم الطلبات مقارنات متعدّدة حتى يقارن التقرير بين هذه المقارنات.

تمثيل JSON 
{
  "name": string,

  // Union field one_comparison can be only one of the following:
  "dimensionFilter": {
    object (FilterExpression)
  },
  "comparison": string
  // End of list of possible types for union field one_comparison.
}
الحقول
name

string

تنتج كل مقارنة صفوفًا منفصلة في الردّ. في الردّ، يتم تحديد هذه المقارنة بهذا الاسم. إذا لم يتم تحديد الاسم، سنستخدم الاسم المعروض للمقارنات المحفوظة.

حقل الربط one_comparison

يمكن أن يكون التعليق one_comparison إحدى القيم التالية فقط:
dimensionFilter

object (FilterExpression)

مقارنة أساسية
comparison

string

مقارنة محفوظة يتم تحديدها من خلال اسم المورد الخاص بالمقارنة على سبيل المثال، "comparisons/1234".

ConversionSpec

تتحكّم هذه السمة في إعداد تقارير الإحالات الناجحة.

تمثيل JSON 
{
  "conversionActions": [
    string
  ],
  "attributionModel": enum (AttributionModel)
}
الحقول
conversionActions[]

string

معرّفات إجراءات الإحالات الناجحة المطلوب تضمينها في التقرير. في حال تركها فارغة، يتم تضمين جميع الإحالات الناجحة. يمكن استرداد أرقام تعريف إجراءات الإحالات الناجحة الصالحة من الحقل conversionAction ضمن القائمة conversions في استجابة الطريقة properties.getMetadata. على سبيل المثال، conversionActions/1234.
attributionModel

enum (AttributionModel)

نموذج تحديد المصدر الذي سيتم استخدامه في "تقرير الإحالات الناجحة" في حال عدم تحديدها، يتم استخدام DATA_DRIVEN.

AttributionModel

نموذج تحديد المصدر الذي سيتم استخدامه في "تقرير الإحالات الناجحة"

عمليات التعداد
ATTRIBUTION_MODEL_UNSPECIFIED نموذج تحديد المصدر غير محدّد.
DATA_DRIVEN تم تحديد المصدر استنادًا إلى نموذج تحديد المصدر بالاستناد إلى البيانات في القنوات المدفوعة وبيانات الأداء بدون إعلانات
LAST_CLICK استند تحديد المصدر إلى نموذج النقرة الأخيرة على القنوات المدفوعة والمجانية