Method: properties.runReport

یک گزارش سفارشی از داده‌های رویداد گوگل آنالیتیکس شما را برمی‌گرداند. گزارش‌ها حاوی آماری هستند که از داده‌های جمع‌آوری‌شده توسط کد رهگیری گوگل آنالیتیکس استخراج شده‌اند. داده‌های برگردانده‌شده از API به صورت جدولی با ستون‌هایی برای ابعاد و معیارهای درخواستی هستند. معیارها، اندازه‌گیری‌های فردی از فعالیت کاربر در سایت شما، مانند کاربران فعال یا تعداد رویدادها، هستند. ابعاد، معیارها را بر اساس برخی معیارهای رایج، مانند کشور یا نام رویداد، تجزیه می‌کنند.

درخواست HTTP

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

این URL از سینتکس Transcoding در gRPC استفاده می‌کند.

پارامترهای مسیر

پارامترها
property

string

الزامی. یک شناسه ویژگی گوگل آنالیتیکس که رویدادهای آن ردیابی می‌شوند. در مسیر URL مشخص شده است و نه در بدنه. برای کسب اطلاعات بیشتر، به محل یافتن شناسه ویژگی خود مراجعه کنید. در یک درخواست دسته‌ای، این ویژگی یا باید نامشخص باشد یا با ویژگی سطح دسته‌ای سازگار باشد.

مثال: ویژگی‌ها/۱۲۳۴

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

نمایش 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)

اختیاری. تعداد ردیف ردیف شروع. ردیف اول به عنوان ردیف ۰ شمرده می‌شود.

هنگام صفحه‌بندی، درخواست اول آفست را مشخص نمی‌کند؛ یا به طور معادل، آفست را روی ۰ تنظیم می‌کند؛ درخواست اول limit اول ردیف‌ها را برمی‌گرداند. درخواست دوم آفست را روی limit درخواست اول تنظیم می‌کند؛ درخواست دوم limit دوم ردیف‌ها را برمی‌گرداند.

برای کسب اطلاعات بیشتر در مورد این پارامتر صفحه‌بندی، به صفحه‌بندی مراجعه کنید.

limit

string ( int64 format)

اختیاری. حداکثر تعداد ردیف‌هایی که باید برگردانده شوند. اگر مشخص نشود، ۱۰۰۰۰ ردیف برگردانده می‌شود. API حداکثر ۲۵۰۰۰۰ ردیف را در هر درخواست برمی‌گرداند، مهم نیست چند ردیف درخواست کنید. limit باید مثبت باشد.

اگر تعداد مقادیر بُعد به اندازه‌ی limit نباشد، API می‌تواند تعداد ردیف‌های کمتری نسبت به limit درخواستی برگرداند. برای مثال، کمتر از ۳۰۰ مقدار ممکن برای بُعد country وجود دارد، بنابراین هنگام گزارش‌گیری فقط بر اساس country ، نمی‌توانید بیش از ۳۰۰ ردیف دریافت کنید، حتی اگر limit روی مقدار بالاتری تنظیم کنید.

برای کسب اطلاعات بیشتر در مورد این پارامتر صفحه‌بندی، به صفحه‌بندی مراجعه کنید.

metricAggregations[]

enum ( MetricAggregation )

اختیاری. تجمیع معیارها. مقادیر تجمیع‌شده معیارها در ردیف‌هایی نشان داده می‌شوند که در آن‌ها مقادیر بُعد روی "RESERVED_(MetricAggregation)" تنظیم شده‌اند. تجمیع‌ها شامل مقایسه‌ها و چندین محدوده تاریخ بر اساس محدوده‌های تاریخ تجمیع می‌شوند.

orderBys[]

object ( OrderBy )

اختیاری. نحوه مرتب‌سازی ردیف‌ها در پاسخ را مشخص می‌کند. درخواست‌هایی که شامل مقایسه‌ها و چندین محدوده تاریخ هستند، ترتیب مقایسه‌ها را اعمال می‌کنند.

currencyCode

string

اختیاری. یک کد ارز با فرمت ISO4217، مانند "AED"، "USD"، "JPY". اگر فیلد خالی باشد، گزارش از ارز پیش‌فرض ملک استفاده می‌کند.

cohortSpec

object ( CohortSpec )

اختیاری. گروه هم‌گروهی مرتبط با این درخواست. اگر یک گروه هم‌گروهی در درخواست وجود دارد، بُعد «هم‌گروهی» باید موجود باشد.

keepEmptyRows

boolean

اختیاری. اگر نادرست یا نامشخص باشد، هر ردیفی که تمام معیارهای آن برابر با ۰ باشد، بازگردانده نمی‌شود. اگر درست باشد، این ردیف‌ها در صورتی که جداگانه توسط فیلتر حذف نشده باشند، بازگردانده می‌شوند.

صرف نظر از این تنظیم keepEmptyRows ، فقط داده‌های ثبت‌شده توسط ویژگی Google Analytics می‌توانند در یک گزارش نمایش داده شوند.

برای مثال، اگر یک ویژگی هرگز رویداد purchase را ثبت نکند، آنگاه یک پرس‌وجو برای بُعد eventName و معیار eventCount ، ردیف eventName: "purchase" و eventCount: 0 نخواهد داشت.

returnPropertyQuota

boolean

اختیاری. وضعیت فعلی سهمیه این ویژگی گوگل آنالیتیکس را برمی‌گرداند یا خیر. سهمیه در 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 و ترتیب DimensionHeaders با ابعاد موجود در ردیف‌ها مطابقت دارد.

metricHeaders[]

object ( MetricHeader )

ستون‌های متریک را توصیف می‌کند. تعداد MetricHeaders و ترتیب MetricHeaders با معیارهای موجود در ردیف‌ها مطابقت دارد.

rows[]

object ( Row )

ردیف‌هایی از ترکیبات مقادیر بُعد و مقادیر متریک در گزارش.

totals[]

object ( Row )

در صورت درخواست، مجموع مقادیر معیارها.

maximums[]

object ( Row )

در صورت درخواست، حداکثر مقادیر معیارها.

minimums[]

object ( Row )

در صورت درخواست، حداقل مقادیر معیارها.

rowCount

integer

تعداد کل ردیف‌ها در نتیجه‌ی پرس‌وجو، صرف نظر از تعداد ردیف‌های برگردانده شده در پاسخ. برای مثال، اگر یک پرس‌وجو ۱۷۵ ردیف برگرداند و در درخواست API مقدار limit = 50 را وارد کند، پاسخ شامل rowCount = 175 خواهد بود، اما فقط ۵۰ ردیف دارد.

برای کسب اطلاعات بیشتر در مورد این پارامتر صفحه‌بندی، به صفحه‌بندی مراجعه کنید.

metadata

object ( ResponseMetaData )

متادیتا برای گزارش.

propertyQuota

object ( PropertyQuota )

وضعیت سهمیه این Analytics Property شامل این درخواست می‌شود.

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'.

مشخصات تبدیل

گزارش تبدیل را کنترل می‌کند.

نمایش JSON 
{
  "conversionActions": [
    string
  ],
  "attributionModel": enum (AttributionModel)
}
فیلدها
conversionActions[]

string

شناسه‌های عملیات تبدیل که باید در گزارش لحاظ شوند. اگر خالی باشد، همه تبدیل‌ها لحاظ می‌شوند. شناسه‌های معتبر عملیات تبدیل را می‌توان از فیلد conversionAction در لیست conversions در پاسخ متد properties.getMetadata بازیابی کرد. برای مثال، 'conversionActions/1234'.

attributionModel

enum ( AttributionModel )

مدل انتساب مورد استفاده در گزارش تبدیل. در صورت عدم تعیین، DATA_DRIVEN استفاده می‌شود.

مدل انتساب

مدل انتساب برای استفاده در گزارش تبدیل

انوم‌ها
ATTRIBUTION_MODEL_UNSPECIFIED مدل انتساب نامشخص.
DATA_DRIVEN انتساب بر اساس مدل پولی و داده‌محور ارگانیک بود
LAST_CLICK انتساب بر اساس مدل آخرین کلیک پولی و ارگانیک بود