ویژگی‌های استاندارد Universal Analytics (UA) پردازش داده‌ها را در 1 ژوئیه 2023 متوقف کردند . دارایی‌های UA 360 پردازش داده‌ها را در تاریخ 1 ژوئیه 2024 متوقف خواهند کرد و برخی از ویژگی‌های UA 360 قبل از آن منسوخ خواهند شد ، زیرا ما به Google Analytics 4 منتقل می‌شویم . از Data API برای دسترسی به ویژگی های گزارش برای ویژگی های GA4 استفاده کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

Core Reporting API - Reference Guide, Core Reporting API - Reference Guide

این سند مرجع کاملی برای پرس و جو و پاسخ برای Core Reporting API نسخه 3.0 ارائه می دهد.

معرفی

شما از Core Reporting API برای داده های گزارش Google Analytics سؤال می کنید. هر پرس و جو به شناسه نما (نمایه)، تاریخ شروع و پایان و حداقل یک معیار نیاز دارد. همچنین می‌توانید پارامترهای پرس و جوی دیگری مانند ابعاد، فیلترها و بخش‌ها را برای اصلاح درخواست خود ارائه دهید. برای درک اینکه چگونه همه این مفاهیم با هم کار می کنند ، راهنمای نمای کلی را ببینید.

درخواست

API یک روش واحد برای درخواست داده ارائه می دهد:

analytics.data.ga.get()

این روش در کتابخانه های مختلف کلاینت در معرض دید قرار می گیرد و دارای رابط های زبان خاص برای تنظیم پارامترهای پرس و جو است.

API همچنین می تواند به عنوان یک نقطه پایانی REST-ful مورد جستجو قرار گیرد:

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/ga
  ?ids=ga:12345
  &start-date=2008-10-01
  &end-date=2008-10-31
  &metrics=ga:sessions,ga:bounces

هر پارامتر پرس و جو URL یک پارامتر پرس و جوی API را مشخص می کند که باید URL کدگذاری شده باشد .

خلاصه پارامترهای پرس و جو

جدول زیر تمام پارامترهای پرس و جو پذیرفته شده توسط Core reporting API را خلاصه می کند. برای توضیح دقیق روی نام هر پارامتر کلیک کنید.

نام	ارزش	ضروری	خلاصه
`ids`	`string`	آره	شناسه جدول منحصر به فرد فرم ga:XXXX، که در آن XXXX شناسه نمای آنالیتیکس (نمایه) است که پرس و جو داده ها را برای آن بازیابی می کند.
`start-date`	`string`	آره	تاریخ شروع برای واکشی داده های Analytics. درخواست‌ها می‌توانند تاریخ شروع را با فرمت `YYYY-MM-DD` یا به عنوان یک تاریخ نسبی (مثلاً `today` ، `yesterday` یا `NdaysAgo` که در آن `N` یک عدد صحیح مثبت است) تعیین کنند.
`end-date`	`string`	آره	تاریخ پایان برای واکشی داده های Analytics. درخواست می‌تواند تاریخ پایانی را با فرمت `YYYY-MM-DD` یا به عنوان یک تاریخ نسبی مشخص کند (به عنوان مثال، `today` ، `yesterday` یا `NdaysAgo` که در آن `N` یک عدد صحیح مثبت است).
`metrics`	`string`	آره	فهرستی از معیارهای جدا شده با کاما، مانند `ga:sessions,ga:bounces` .
`dimensions`	`string`	نه	فهرستی از ابعاد جدا شده با کاما برای داده های Analytics شما، مانند `ga:browser,ga:city` .
`sort`	`string`	نه	فهرستی از ابعاد و معیارهای جدا شده با کاما که ترتیب مرتب سازی و جهت مرتب سازی داده های برگشتی را نشان می دهد.
`filters`	`string`	نه	فیلترهای ابعاد یا متریک که داده های بازگردانده شده برای درخواست شما را محدود می کند.
`segment`	`string`	نه	داده های بازگردانده شده برای درخواست شما را بخش بندی می کند.
`samplingLevel`	`string`	نه	سطح نمونه گیری مورد نظر. مقادیر مجاز: `DEFAULT` - پاسخ را با اندازه نمونه برمی‌گرداند که سرعت و دقت را متعادل می‌کند. `FASTER` - پاسخ سریع با حجم نمونه کوچکتر را برمی گرداند. `HIGHER_PRECISION` - با استفاده از حجم نمونه بزرگ، پاسخ دقیق تری را نشان می دهد، اما ممکن است منجر به کندتر شدن پاسخ شود.
`include-empty-rows`	`boolean`	نه	پیش فرض ها به true; اگر روی false تنظیم شود، سطرهایی که تمام مقادیر متریک آنها صفر هستند از پاسخ حذف می شوند.
`start-index`	`integer`	نه	اولین ردیف داده برای بازیابی، از 1 شروع می شود. از این پارامتر به عنوان مکانیزم صفحه بندی همراه با پارامتر `max-results` استفاده کنید.
`max-results`	`integer`	نه	حداکثر تعداد ردیف هایی که باید در پاسخ گنجانده شود.
`output`	`string`	نه	نوع خروجی مورد نظر برای داده های Analytics که در پاسخ بازگردانده شده است. مقادیر قابل قبول `json` و `dataTable` هستند. پیش فرض: `json` .
`fields`	`string`	نه	انتخابگر که زیر مجموعه ای از فیلدها را برای درج در پاسخ مشخص می کند.
`prettyPrint`	`string`	نه	پاسخ را با تورفتگی و شکستگی برمی‌گرداند. `false` پیش فرض
`userIp`	`string`	نه	آدرس IP کاربر نهایی را که تماس API برای او انجام می شود را مشخص می کند. برای سقف استفاده در هر IP استفاده می شود.
`quotaUser`	`string`	نه	جایگزینی برای userIp در مواردی که آدرس IP کاربر ناشناخته است.
`access_token`	`string`	نه	یکی از راه های ممکن برای ارائه توکن OAuth 2.0 .
`callback`	`string`	نه	نام تابع فراخوانی جاوا اسکریپت که پاسخ را مدیریت می کند. در درخواست های جاوا اسکریپت JSON-P استفاده می شود.
`key`	`string`	نه	برای مجوز OAuth 1.0a برای تعیین برنامه شما برای دریافت سهمیه استفاده می شود. به عنوان مثال: `key= AldefliuhSFADSfasdfasdfASdf` .

جزئیات پارامتر پرس و جو

شناسه

ids= ga:12345

ضروری.

شناسه منحصر به فرد مورد استفاده برای بازیابی داده های Analytics. این شناسه ترکیبی از فضای نام ga: با شناسه نمای (نمایه) Analytics است. می‌توانید شناسه view (نمایه) را با استفاده از روش analytics.management.profiles.list ، که id در منبع View (نمایه) در API مدیریت Google Analytics ارائه می‌کند، بازیابی کنید.

تاریخ شروع

start-date= 2009-04-20

ضروری.

همه درخواست‌های داده Analytics باید یک محدوده تاریخی را مشخص کنند. اگر پارامترهای start-date و end-date در درخواست وارد نکنید، سرور یک خطا را برمی‌گرداند. مقادیر تاریخ می توانند برای یک تاریخ خاص با استفاده از الگوی YYYY-MM-DD یا نسبی با استفاده از today ، yesterday یا الگوی NdaysAgo باشند. مقادیر باید با [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) مطابقت داشته باشند.

اولین start-date معتبر 2005-01-01 است. محدودیت بالایی برای تاریخ شروع وجود ندارد.

تاریخ های نسبی همیشه نسبت به تاریخ فعلی در زمان پرس و جو هستند و بر اساس منطقه زمانی نمای (پروفایل) مشخص شده در پرس و جو هستند.

نمونه محدوده تاریخ برای 7 روز گذشته (از دیروز) با استفاده از تاریخ های نسبی:

  &start-date=7daysAgo
  &end-date=yesterday

تاریخ پایان

end-date= 2009-05-20

ضروری.

اولین end-date معتبر 2005-01-01 است. محدودیت بالایی برای end-date وجود ندارد.

نمونه محدوده تاریخ برای 10 روز گذشته (از امروز) با استفاده از تاریخ های نسبی:

  &start-date=9daysAgo
  &end-date=today

ابعاد

dimensions= ga:browser,ga:city

اختیاری.

پارامتر dimensions ، معیارها را با معیارهای رایج تجزیه می کند. برای مثال، توسط ga:browser یا ga:city . در حالی که می توانید تعداد کل بازدید از صفحه سایت خود را بپرسید، ممکن است جالب تر باشد که تعداد بازدیدهای صفحه را به تفکیک مرورگر بپرسید. در این حالت، تعداد بازدیدهای صفحه از فایرفاکس، اینترنت اکسپلورر، کروم و غیره را خواهید دید.

هنگام استفاده از dimensions در درخواست داده، از محدودیت های زیر آگاه باشید:

شما می توانید حداکثر 7 بعد را در هر پرس و جو ارائه کنید.
شما نمی توانید درخواستی را ارسال کنید که فقط از ابعاد تشکیل شده باشد: باید هر ابعاد درخواستی را با حداقل یک متریک ترکیب کنید.
فقط برخی از ابعاد را می توان در همان پرس و جو جستجو کرد. از ابزار ترکیبی معتبر در مرجع ابعاد و متریک استفاده کنید تا ببینید کدام ابعاد را می توان با هم استفاده کرد.

معیارهای

metrics= ga:sessions,ga:bounces

ضروری.

آمار جمع آوری شده برای فعالیت کاربر در سایت شما، مانند کلیک ها یا بازدید از صفحه. اگر پرس و جو فاقد پارامتر dimensions باشد، معیارهای برگردانده شده مقادیر مجموعی را برای محدوده تاریخ درخواستی، مانند بازدیدهای کلی از صفحه یا کل پرش ها، ارائه می کنند. با این حال، هنگامی که ابعاد درخواست می شود، مقادیر بر اساس مقدار ابعاد تقسیم می شوند. به عنوان مثال، ga:pageviews درخواست شده با ga:country کل بازدیدهای صفحه در هر کشور را برمی گرداند. هنگام درخواست معیارها، به خاطر داشته باشید:

هر درخواستی باید حداقل یک متریک ارائه کند. یک درخواست نمی تواند فقط شامل ابعاد باشد.
شما می توانید حداکثر 10 معیار برای هر پرس و جو ارائه کنید.
اکثر ترکیبات معیارهای چند دسته را می توان با هم استفاده کرد، مشروط بر اینکه هیچ ابعادی مشخص نشده باشد.
یک متریک را می توان در ترکیب با سایر ابعاد یا معیارها استفاده کرد، اما فقط در مواردی که ترکیبات معتبر برای آن معیار اعمال می شود. برای جزئیات به مرجع ابعاد و متریک مراجعه کنید.

مرتب سازی

sort= ga:country,ga:browser

اختیاری.

فهرستی از معیارها و ابعاد که ترتیب مرتب سازی و جهت مرتب سازی داده های برگشتی را نشان می دهد.

ترتیب مرتب سازی با ترتیب از چپ به راست معیارها و ابعاد فهرست شده مشخص می شود.
جهت مرتب سازی به طور پیش فرض صعودی است و می توان آن را با استفاده از پیشوند علامت منفی ( - ) در فیلد درخواستی به نزولی تغییر داد.

مرتب سازی نتایج یک پرس و جو به شما امکان می دهد سوالات مختلفی را در مورد داده های خود بپرسید. به عنوان مثال، برای پاسخ به این سوال "کشورهای برتر من کدامند و از کدام مرورگرها بیشتر استفاده می کنند؟" می توانید با پارامتر زیر یک پرس و جو ایجاد کنید. ابتدا بر اساس ga:country و سپس بر اساس ga:browser ، هر دو به ترتیب صعودی مرتب می شود:

sort=ga:country,ga:browser

برای پاسخ به سوال مرتبط "برترین مرورگرهای من کدامند و کدام کشورها بیشتر از آنها استفاده می کنند؟"، می توانید با پارامتر زیر پرس و جو کنید. ابتدا بر اساس ga:browser و سپس بر اساس ga:country ، هر دو به ترتیب صعودی مرتب می شود:

sort=ga:browser,ga:country

هنگام استفاده از پارامتر sort ، موارد زیر را در نظر داشته باشید:

فقط بر اساس ابعاد یا مقادیر معیارهایی که در dimensions یا پارامترهای metrics استفاده کرده اید مرتب کنید. اگر درخواست شما در فیلدی که در پارامتر ابعاد یا متریک مشخص نشده است مرتب شود، یک خطا دریافت خواهید کرد.
به‌طور پیش‌فرض، رشته‌ها به ترتیب حروف الفبای صعودی در محلی en-US مرتب می‌شوند.
اعداد به طور پیش فرض به ترتیب عددی صعودی مرتب شده اند.
تاریخ ها به طور پیش فرض بر اساس تاریخ به ترتیب صعودی مرتب شده اند.

فیلترها

filters=ga:medium%3D%3Dreferral

نحو فیلتر
اپراتورهای فیلتر
عبارات فیلتر
ترکیب فیلترها
- اپراتور OR
- و اپراتور

اختیاری.

پارامتر رشته پرس و جو filters داده های برگشتی از درخواست شما را محدود می کند. برای استفاده از پارامتر filters ، یک بعد یا متریک برای فیلتر و به دنبال آن عبارت فیلتر ارائه دهید. به عنوان مثال، پرس و جو زیر ga:pageviews و ga:browser برای مشاهده (پروفایل) 12134 درخواست می کند، جایی که بعد ga:browser با رشته Firefox شروع می شود:

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

پرس و جوهای فیلتر شده، ردیف هایی را که در نتیجه گنجانده می شوند (یا نمی شوند) محدود می کنند. هر ردیف در نتیجه در برابر فیلتر آزمایش می شود: اگر فیلتر مطابقت داشته باشد، ردیف حفظ می شود و اگر مطابقت نداشته باشد، ردیف حذف می شود.

رمزگذاری URL : کتابخانه های سرویس گیرنده Google API به طور خودکار اپراتورهای فیلتر را رمزگذاری می کنند.
فیلتر ابعاد : فیلتر قبل از انباشته شدن هر یک از ابعاد اتفاق می‌افتد، به طوری که معیارهای برگشتی مجموع را فقط برای ابعاد مربوطه نشان می‌دهد. در مثال بالا، تعداد بازدید از صفحه فقط همان بازدیدهایی است که مرورگر فایرفاکس است.
فیلتر معیارها : فیلتر کردن معیارها پس از جمع‌آوری معیارها انجام می‌شود.
ترکیب‌های معتبر : می‌توانید برای یک بعد یا معیاری که بخشی از درخواست شما نیست فیلتر کنید، مشروط بر اینکه همه ابعاد/متریک‌های موجود در درخواست و فیلتر ترکیب‌های معتبری باشند. به عنوان مثال، ممکن است بخواهید فهرستی از تاریخ بازدید از صفحه را جستجو کنید و در یک مرورگر خاص فیلتر کنید. برای اطلاعات بیشتر به مرجع ابعاد و متریک مراجعه کنید.

نحو فیلتر

یک فیلتر واحد از فرم زیر استفاده می کند:

ga:name operator expression

در این نحو:

name - نام بعد یا متریک برای فیلتر کردن. به عنوان مثال: فیلترهای ga:pageviews در متریک بازدید از صفحه.
اپراتور - نوع تطبیق فیلتر را برای استفاده تعریف می کند. اپراتورها به ابعاد یا معیارها اختصاص دارند.
بیان - مقادیری را که باید در نتایج گنجانده شوند یا از نتایج حذف شوند را بیان می کند. عبارات از نحو عبارت منظم استفاده می کنند.

اپراتورهای فیلتر

شش عملگر فیلتر برای ابعاد و شش عملگر فیلتر برای معیارها وجود دارد. عملگرها باید با URL کدگذاری شوند تا در رشته‌های پرس و جو URL گنجانده شوند.

نکته : از Data Feed Query Explorer برای طراحی فیلترهایی که نیاز به رمزگذاری URL دارند استفاده کنید، زیرا Query Explorer به طور خودکار URL های حاوی رشته ها و فاصله ها را رمزگذاری می کند.

**فیلترهای متریک**
اپراتور	شرح	فرم رمزگذاری شده URL	مثال ها
`==`	برابر است	`%3D%3D`	نتایج را در جایی که زمان در صفحه دقیقاً ده ثانیه است برگردانید: `filters=ga:timeOnPage%3D%3D10`
`!=`	برابر نیست	`!%3D`	نتایج را در جایی که زمان در صفحه ده ثانیه نیست برگردانید: `filters=ga:timeOnPage!%3D10`
`>`	بزرگتر از	`%3E`	نتایج را در جایی برگردانید که زمان در صفحه به شدت بیشتر از ده ثانیه باشد: `filters=ga:timeOnPage%3E10`
`<`	کمتر از	`%3C`	نتایج را در جایی که زمان در صفحه به طور دقیق کمتر از ده ثانیه است برگردانید: `filters=ga:timeOnPage%3C10`
`>=`	بزرگتر یا مساوی با	`%3E%3D`	نتایج را در جایی که زمان در صفحه ده ثانیه یا بیشتر است برگردانید: `filters=ga:timeOnPage%3E%3D10`
`<=`	کمتر یا مساوی با	`%3C%3D`	نتایج را در جایی که زمان در صفحه ده ثانیه یا کمتر است برگردانید: `filters=ga:timeOnPage%3C%3D10`

**فیلترهای ابعاد**
اپراتور	شرح	فرم رمزگذاری شده URL	مثال
`==`	مطابقت کامل	`%3D%3D`	معیارهای مجموع جایی که شهر ایروین است: `filters=ga:city%3D%3DIrvine`
`!=`	مطابقت ندارد	`!%3D`	معیارهای مجموع در جایی که شهر ایروین نیست : `filters=ga:city!%3DIrvine`
`=@`	حاوی رشته فرعی	`%3D@`	معیارهای انبوه در جایی که شهر حاوی یورک است: `filters=ga:city%3D@York`
`!@`	شامل رشته فرعی نیست	`!@`	معیارهای مجموع در جایی که شهر شامل یورک نیست: `filters=ga:city!@York`
`=~`	شامل یک مسابقه برای عبارت منظم است	`%3D~`	معیارهای انبوه جایی که شهر با New شروع می شود: `filters=ga:city%3D~%5ENew.*` (%5E URL کدگذاری شده از کاراکتر ^ است که یک الگو را به ابتدای رشته متصل می کند.)
`!~`	با عبارت منظم مطابقت ندارد	`!~`	معیارهای انبوه در جایی که شهر با New شروع نمی شود: `filters=ga:city!~%5ENew.*`

عبارات فیلتر

چند قانون مهم برای عبارات فیلتر وجود دارد:

کاراکترهای رزرو شده توسط URL - کاراکترهایی مانند & باید به روش معمول با URL کدگذاری شوند.
کاراکترهای رزرو شده - هنگامی که در یک عبارت ظاهر می شوند، نقطه ویرگول و کاما باید به صورت بک اسلش خارج شوند:
- نقطه ویرگول \;
- کاما \,
عبارات منظم - همچنین می توانید از عبارات منظم در عبارات فیلتر با استفاده از عملگرهای =~ و !~ استفاده کنید. نحو آنها شبیه عبارات منظم پرل است و این قوانین اضافی را دارد:
- حداکثر طول 128 کاراکتر - عبارات معمولی بیش از 128 کاراکتر منجر به 400 Bad Request از سرور می شود.
- حساسیت به حروف کوچک و بزرگ - تطبیق عبارت منظم به حروف بزرگ و کوچک حساس نیست.

ترکیب فیلترها

فیلترها را می توان با استفاده از منطق بولی OR و AND ترکیب کرد. این به شما امکان می دهد تا حد 128 کاراکتری یک عبارت فیلتر را به طور موثر افزایش دهید.

یا

عملگر OR با استفاده از کاما ( , ) تعریف می شود. بر عملگر AND اولویت دارد و ممکن است برای ترکیب ابعاد و معیارها در یک عبارت استفاده نشود.

مثال‌ها: (هر کدام باید URL کدگذاری شده باشند)

کشور یکی است (ایالات متحده یا کانادا):
ga:country==United%20States,ga:country==Canada

کاربران فایرفاکس در سیستم عامل (ویندوز یا مکینتاش):
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

و

عملگر AND با استفاده از نیم دونقطه ( ; ) تعریف می شود. قبل از آن عملگر OR وجود دارد و می توان از آن برای ترکیب ابعاد و معیارها در یک عبارت استفاده کرد.

مثال‌ها: (هر کدام باید URL کدگذاری شده باشند)

کشور ایالات متحده و مرورگر فایرفاکس است:
ga:country==United%20States;ga:browser==Firefox

کشور ایالات متحده است و زبان با 'en' شروع نمی شود:
ga:country==United%20States;ga:language!~^en.*

سیستم عامل (ویندوز یا مکینتاش) و مرورگر (فایرفاکس یا کروم):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome

کشور ایالات متحده است و تعداد جلسات بیشتر از 5 است:
ga:country==United%20States;ga:sessions>5

بخش

segment=gaid::-10
 segment=sessions::condition::ga:medium%3D%3Dreferral
 segment=users::condition::ga:browser%3D%3DChrome

اختیاری.

برای جزئیات کامل در مورد نحوه درخواست یک بخش در Core Reporting API به راهنمای توسعه بخش Segments مراجعه کنید.

برای یک نمای کلی مفهومی از بخش‌ها، به بخش مرجع و بخش‌های ویژگی در مرکز راهنمایی مراجعه کنید.

ابعاد و معیارهای مجاز در بخش‌ها.
همه ابعاد و معیارها را نمی توان در بخش ها استفاده کرد. برای بررسی ابعاد و معیارهای مجاز در بخش‌ها از کاوشگر ابعاد و متریک دیدن کنید.

توجه : پیشوند dynamic:: از تاریخ 27 مارس 2014 منسوخ شده است. توصیه می شود در اسرع وقت به نحو جدید مهاجرت کنید.

samplingLevel

samplingLevel=DEFAULT

اختیاری.

از این پارامتر برای تنظیم سطح نمونه برداری (یعنی تعداد جلسات استفاده شده برای محاسبه نتیجه) برای یک درخواست گزارش استفاده کنید. مقادیر مجاز با رابط وب سازگار است و شامل موارد زیر است:

DEFAULT - پاسخ را با اندازه نمونه برمی‌گرداند که سرعت و دقت را متعادل می‌کند.
FASTER - پاسخ سریع با حجم نمونه کوچکتر را برمی گرداند.
HIGHER_PRECISION - با استفاده از حجم نمونه بزرگ، پاسخ دقیق تری را نشان می دهد، اما ممکن است منجر به کندتر شدن پاسخ شود.

در صورت عدم ارائه، از سطح نمونه گیری DEFAULT استفاده خواهد شد.

برای جزئیات نحوه محاسبه درصد جلساتی که برای یک پرس و جو استفاده شده است، به بخش Sampling مراجعه کنید.

شامل-خالی-ردیف ها

include-empty-rows=true

اختیاری.

پیش فرض ها به true; اگر روی false تنظیم شود، سطرهایی که تمام مقادیر متریک آنها صفر هستند از پاسخ حذف می شوند. به عنوان مثال، اگر بیش از یک متریک را در یک پرس و جو قرار دهید، ردیف ها تنها در صورتی حذف می شوند که همه مقادیر متریک صفر باشند. این می تواند هنگام درخواستی که انتظار می رود تعداد ردیف های معتبر بسیار کمتر از تعداد مقادیر ابعاد مورد انتظار باشد، مفید باشد.

شروع-شاخص

start-index=10

اختیاری.

اگر ارائه نشود، شاخص شروع 1 است. (شاخص‌های نتایج بر اساس 1 هستند. یعنی ردیف اول ردیف 1 است نه ردیف 0 ) از این پارامتر به عنوان مکانیزم صفحه‌بندی به همراه پارامتر max-results برای موقعیت‌هایی استفاده کنید که totalResults از 10000 فراتر می‌رود و می‌خواهید ردیف‌های نمایه‌شده را بازیابی کنید. در 10001 و بالاتر.

حداکثر نتایج

max-results=100

اختیاری.

حداکثر تعداد ردیف هایی که باید در این پاسخ گنجانده شود. می‌توانید از آن در ترکیب با start-index برای بازیابی زیرمجموعه‌ای از عناصر استفاده کنید، یا از آن به تنهایی برای محدود کردن تعداد عناصر بازگشتی استفاده کنید، از اول شروع کنید. اگر max-results ارائه نشود، پرس و جو حداکثر 1000 ردیف را برمی گرداند.

Analytics Core Reporting API حداکثر 10000 ردیف را در هر درخواست برمی گرداند، مهم نیست که چقدر درخواست کنید. همچنین می‌تواند ردیف‌های کمتری را نسبت به درخواستی بازگرداند، اگر بخش‌های بعدی آن‌قدر که انتظار دارید وجود نداشته باشد. به عنوان مثال، کمتر از 300 مقدار ممکن برای ga:country وجود دارد، بنابراین هنگام تقسیم بندی فقط بر اساس کشور، نمی توانید بیش از 300 ردیف دریافت کنید، حتی اگر max-results روی یک مقدار بالاتر تنظیم کنید.

خروجی

output=dataTable

اختیاری.

از این پارامتر برای تنظیم نوع خروجی داده های Analytics بازگردانده شده در پاسخ استفاده کنید. مقادیر مجاز عبارتند از:

json - ویژگی rows پیش فرض را در پاسخ، حاوی یک شی JSON، خروجی می دهد.
dataTable - یک ویژگی dataTable را در پاسخ خروجی می دهد که حاوی یک شی جدول داده است. این شی Data Table می توان مستقیماً با تجسم نمودارهای Google استفاده کرد.

اگر ارائه نشده باشد، از پاسخ پیش‌فرض JSON استفاده خواهد شد.

زمینه های

fields=rows,columnHeaders(name,dataType)

اختیاری.

مشخص می کند که کدام فیلدها در یک پاسخ جزئی بازگردانده شوند. اگر فقط از زیرمجموعه ای از فیلدها در پاسخ API استفاده می کنید، می توانید از پارامتر fields برای تعیین اینکه کدام فیلدها را شامل شود استفاده کنید.

فرمت مقدار پارامتر درخواست فیلدها بر اساس نحو XPath است. نحو پشتیبانی شده در زیر خلاصه شده است.

از یک لیست جدا شده با کاما برای انتخاب چندین فیلد استفاده کنید.
از a/b برای انتخاب فیلد b که در فیلد a تودرتو است استفاده کنید. از a/b/c برای انتخاب یک فیلد c تو در تو در b استفاده کنید.
از یک انتخابگر فرعی برای درخواست مجموعه ای از فیلدهای فرعی خاص از آرایه ها یا اشیاء با قرار دادن عبارات در پرانتز "( )" استفاده کنید.
به عنوان مثال: fields=columnHeaders(name,dataType) فقط فیلدهای name و dataType را در آرایه columnHeaders برمی گرداند. شما همچنین می توانید یک زیر فیلد را مشخص کنید که در آن fields=columnHeader(name) معادل fields=columnHeader/name باشد.

زیبا پرینت

prettyPrint=false

اختیاری.

اگر true ، پاسخ را در قالبی قابل خواندن برای انسان برمی‌گرداند. مقدار پیش فرض: false .

quotaUser

quotaUser=4kh4r2h4

اختیاری.

به شما امکان می دهد سهمیه های هر کاربر را از یک برنامه سمت سرور حتی در مواردی که آدرس IP کاربر ناشناخته است، اعمال کنید . به عنوان مثال، این می تواند در مورد برنامه هایی رخ دهد که از طرف یک کاربر، cron jobs را در App Engine اجرا می کنند. شما می توانید هر رشته دلخواه را که به طور منحصر به فرد کاربر را شناسایی می کند، انتخاب کنید، اما محدود به 40 کاراکتر است.

اگر هر دو ارائه شده باشند، این userIp را لغو می کند.

واکنش

در صورت موفقیت آمیز بودن، این درخواست یک بدنه پاسخ با ساختار JSON تعریف شده در زیر برمی گرداند. اگر پارامتر خروجی روی dataTable تنظیم شود، درخواست یک بدنه پاسخ با ساختار JSON (جدول داده) تعریف شده در زیر برمی گرداند.

توجه : عبارت "نتایج" به کل مجموعه سطرهایی اشاره دارد که با پرس و جو مطابقت دارند، در حالی که "پاسخ" به مجموعه ردیف هایی اشاره دارد که در صفحه فعلی نتایج بازگردانده شده اند. همانطور که در itemsPerPage توضیح داده شده است، اگر تعداد کل نتایج از اندازه صفحه برای پاسخ فعلی بیشتر باشد، می توانند متفاوت باشند.

JSON

{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "include-empty-rows": boolean
    "samplingLevel": string,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

فیلدهای پاسخ

خواص ساختار بدن پاسخ به شرح زیر تعریف می شود:

نام ملک	ارزش	شرح
`kind`	`string`	نوع منبع مقدار "analytics#gaData" است.
`id`	`string`	شناسه ای برای این پاسخ داده.
`query`	`object`	این شی شامل تمام مقادیر ارسال شده به عنوان پارامتر به پرس و جو است. معنی هر فیلد در توضیح پارامتر پرس و جوی مربوطه آن توضیح داده شده است.
`query.start-date`	`string`	تاریخ شروع.
`query.end-date`	`string`	تاریخ پایان.
`query.ids`	`string`	شناسه جدول منحصر به فرد
`query.dimensions[]`	`list`	فهرست ابعاد تجزیه و تحلیل
`query.metrics[]`	`list`	فهرست معیارهای تحلیلی
`query.samplingLevel`	`string`	`Requested sampling level.`
`query.include-empty-rows`	`boolean`	پیش فرض ها به true; اگر روی false تنظیم شود، سطرهایی که تمام مقادیر متریک آنها صفر هستند از پاسخ حذف می شوند.
`query.sort[]`	`list`	فهرست معیارها یا ابعادی که داده ها بر اساس آنها مرتب شده اند.
`query.filters`	`string`	فهرست فیلترهای متریک یا ابعاد جدا شده با کاما.
`query.segment`	`string`	بخش تجزیه و تحلیل.
`query.start-index`	`integer`	فهرست شروع.
`query.max-results`	`integer`	حداکثر نتایج در هر صفحه
`startIndex`	`integer`	شاخص شروع سطرها که توسط پارامتر جستجوی `start-index` مشخص شده است. مقدار پیش فرض 1 است.
`itemsPerPage`	`integer`	حداکثر تعداد ردیف‌هایی که پاسخ می‌تواند داشته باشد، صرف‌نظر از تعداد واقعی ردیف‌های برگشتی. اگر پارامتر query `max-results` مشخص شده باشد، مقدار `itemsPerPage` کوچکتر از `max-results` یا 10000 است. مقدار پیش فرض `itemsPerPage` 1000 است.
`totalResults`	`integer`	تعداد کل ردیف ها در نتیجه پرس و جو، صرف نظر از تعداد ردیف های برگشت داده شده در پاسخ. برای جستارهایی که منجر به تعداد زیادی ردیف می شود، `totalResults` می تواند بزرگتر از `itemsPerPage` باشد. برای توضیحات بیشتر در مورد `totalResults` و `itemsPerPage` برای جستارهای بزرگ به صفحه بندی مراجعه کنید.
`startDate`	`string`	تاریخ شروع برای پرس و جو داده، همانطور که توسط پارامتر `start-date` مشخص شده است.
`endDate`	`string`	تاریخ پایان برای درخواست داده، همانطور که توسط پارامتر `end-date` مشخص شده است.
`selfLink`	`string`	پیوند به این صفحه از نتایج برای این پرسش داده.
`previousLink`	`string`	پیوند به صفحه قبلی نتایج برای این پرسش داده.
`nextLink`	`string`	پیوند به صفحه بعدی نتایج برای این پرسش داده.
`profileInfo`	`object`	اطلاعات مربوط به نمای (نمایه) که داده برای آن درخواست شده است. اطلاعات مشاهده (نمایه) از طریق API مدیریت Google Analytics در دسترس است.
`profileInfo.profileId`	`string`	مشاهده شناسه (نمایه)، مانند `1174` .
`profileInfo.accountId`	`string`	شناسه حسابی که این نما (نمایه) به آن تعلق دارد، مانند `30481` .
`profileInfo.webPropertyId`	`string`	شناسه دارایی وب که این نما (نمایه) به آن تعلق دارد، مانند `UA-30481-1` .
`profileInfo.internalWebPropertyId`	`string`	شناسه داخلی ویژگی وب که این نما (نمایه) به آن تعلق دارد، مانند `UA-30481-1` .
`profileInfo.profileName`	`string`	نام نما (نمایه).
`profileInfo.tableId`	`string`	شناسه جدول برای مشاهده (نمایه)، متشکل از "ga:" و سپس شناسه نمایش (نمایه).
`containsSampledData`	`boolean`	اگر پاسخ حاوی داده های نمونه برداری شده باشد درست است.
`sampleSize`	`string`	تعداد نمونه های مورد استفاده برای محاسبه داده های نمونه برداری شده .
`sampleSpace`	`string`	اندازه کل فضای نمونه برداری این نشان دهنده حجم کل فضای نمونه موجود است که نمونه ها از آن انتخاب شده اند.
`columnHeaders[]`	`list`	سرصفحه‌های ستونی که نام ابعاد را به دنبال نام متریک فهرست می‌کنند. ترتیب ابعاد و معیارها مانند مواردی است که از طریق پارامترهای `metrics` و `dimensions` در درخواست مشخص شده است. تعداد هدرها تعداد ابعاد + تعداد معیارها است.
`columnHeaders[].name`	`string`	نام بعد یا متریک.
`columnHeaders[].columnType`	`string`	نوع ستون. یا "DIMENSION" یا "METRIC".
`columnHeaders[].dataType`	`string`	نوع داده. سرصفحه های ستون ابعاد فقط `STRING` به عنوان نوع داده دارند. سرصفحه های ستون متریک دارای انواع داده برای مقادیر متریک مانند `INTEGER` ، `PERCENT` ، `TIME` ، `CURRENCY` ، `FLOAT` ، و غیره هستند. پاسخ API فراداده را برای همه انواع داده های ممکن مشاهده کنید.
`totalsForAllResults`	`object`	مجموع مقادیر برای معیارهای درخواستی به عنوان جفت نام‌ها و مقادیر معیارهای کلید-مقدار. ترتیب مجموع متریک همان ترتیب متریک مشخص شده در درخواست است.
`rows[]`	`list`	ردیف های داده تجزیه و تحلیل، که در آن هر ردیف حاوی لیستی از مقادیر ابعاد و به دنبال آن مقادیر متریک است. ترتیب ابعاد و معیارها همان است که در درخواست مشخص شده است. هر ردیف فهرستی از N فیلد دارد که در آن N = تعداد ابعاد + تعداد معیارها.

JSON (جدول داده)

{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "samplingLevel": string,
    "include-empty-rows": boolean,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "dataTable": {
    "cols": [
      {
        "id": string,
        "label": string,
        "type": string
      }
    ],
    "rows": [
      {
        "c": [
          {    
            "v": string
          }
        ]
      }   
    ]
  },
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

فیلدهای پاسخ

خواص ساختار بدن پاسخ به شرح زیر تعریف می شود:

نام ملک	ارزش	شرح
`kind`	`string`	نوع منبع مقدار "analytics#gaData" است.
`id`	`string`	شناسه ای برای این پاسخ داده.
`query`	`object`	این شی شامل تمام مقادیر ارسال شده به عنوان پارامتر به پرس و جو است. معنی هر فیلد در توضیح پارامتر پرس و جوی مربوطه آن توضیح داده شده است.
`query.start-date`	`string`	تاریخ شروع.
`query.end-date`	`string`	تاریخ پایان.
`query.ids`	`string`	شناسه جدول منحصر به فرد
`query.dimensions[]`	`list`	فهرست ابعاد تجزیه و تحلیل
`query.metrics[]`	`list`	فهرست معیارهای تحلیلی
`query.samplingLevel`	`string`	`Requested sampling level.`
`query.include-empty-rows`	`boolean`	پیش فرض ها به true; اگر روی false تنظیم شود، سطرهایی که تمام مقادیر متریک آنها صفر هستند از پاسخ حذف می شوند.
`query.sort[]`	`list`	فهرست معیارها یا ابعادی که داده ها بر اساس آنها مرتب شده اند.
`query.filters`	`string`	فهرست فیلترهای متریک یا ابعاد جدا شده با کاما.
`query.segment`	`string`	بخش تجزیه و تحلیل.
`query.start-index`	`integer`	فهرست شروع.
`query.max-results`	`integer`	حداکثر نتایج در هر صفحه
`startIndex`	`integer`	شاخص شروع سطرها که توسط پارامتر جستجوی `start-index` مشخص شده است. مقدار پیش فرض 1 است.
`itemsPerPage`	`integer`	حداکثر تعداد ردیف‌هایی که پاسخ می‌تواند داشته باشد، صرف‌نظر از تعداد واقعی ردیف‌های برگشتی. اگر پارامتر query `max-results` مشخص شده باشد، مقدار `itemsPerPage` کوچکتر از `max-results` یا 10000 است. مقدار پیش فرض `itemsPerPage` 1000 است.
`totalResults`	`integer`	تعداد کل ردیف ها در نتیجه پرس و جو، صرف نظر از تعداد ردیف های برگشت داده شده در پاسخ. برای جستارهایی که منجر به تعداد زیادی ردیف می شود، `totalResults` می تواند بزرگتر از `itemsPerPage` باشد. برای توضیحات بیشتر در مورد `totalResults` و `itemsPerPage` برای جستارهای بزرگ به صفحه بندی مراجعه کنید.
`startDate`	`string`	تاریخ شروع برای پرس و جو داده، همانطور که توسط پارامتر `start-date` مشخص شده است.
`endDate`	`string`	تاریخ پایان برای درخواست داده، همانطور که توسط پارامتر `end-date` مشخص شده است.
`selfLink`	`string`	پیوند به این صفحه از نتایج برای این پرسش داده.
`previousLink`	`string`	پیوند به صفحه قبلی نتایج برای این پرسش داده.
`nextLink`	`string`	پیوند به صفحه بعدی نتایج برای این پرسش داده.
`profileInfo`	`object`	اطلاعات مربوط به نمای (نمایه) که داده برای آن درخواست شده است. اطلاعات مشاهده (نمایه) از طریق API مدیریت Google Analytics در دسترس است.
`profileInfo.profileId`	`string`	مشاهده شناسه (نمایه)، مانند `1174` .
`profileInfo.accountId`	`string`	شناسه حسابی که این نما (نمایه) به آن تعلق دارد، مانند `30481` .
`profileInfo.webPropertyId`	`string`	شناسه دارایی وب که این نما (نمایه) به آن تعلق دارد، مانند `UA-30481-1` .
`profileInfo.internalWebPropertyId`	`string`	شناسه داخلی ویژگی وب که این نما (نمایه) به آن تعلق دارد، مانند `UA-30481-1` .
`profileInfo.profileName`	`string`	نام نما (نمایه).
`profileInfo.tableId`	`string`	شناسه جدول برای مشاهده (نمایه)، متشکل از "ga:" و سپس شناسه نمایش (نمایه).
`containsSampledData`	`boolean`	اگر پاسخ حاوی داده های نمونه برداری شده باشد درست است.
`sampleSize`	`string`	تعداد نمونه های مورد استفاده برای محاسبه داده های نمونه برداری شده .
`sampleSpace`	`string`	اندازه کل فضای نمونه برداری این نشان دهنده حجم کل فضای نمونه موجود است که نمونه ها از آن انتخاب شده اند.
`columnHeaders[]`	`list`	سرصفحه‌های ستونی که نام ابعاد را به دنبال نام متریک فهرست می‌کنند. ترتیب ابعاد و معیارها مانند مواردی است که از طریق پارامترهای `metrics` و `dimensions` در درخواست مشخص شده است. تعداد هدرها تعداد ابعاد + تعداد معیارها است.
`columnHeaders[].name`	`string`	نام بعد یا متریک.
`columnHeaders[].columnType`	`string`	نوع ستون. یا "DIMENSION" یا "METRIC".
`columnHeaders[].dataType`	`string`	نوع داده. سرصفحه های ستون ابعاد فقط `STRING` به عنوان نوع داده دارند. سرصفحه های ستون متریک دارای انواع داده برای مقادیر متریک مانند `INTEGER` ، `PERCENT` ، `TIME` ، `CURRENCY` ، `FLOAT` ، و غیره هستند. پاسخ API فراداده را برای همه انواع داده های ممکن مشاهده کنید.
`totalsForAllResults`	`object`	مجموع مقادیر برای معیارهای درخواستی به عنوان جفت نام‌ها و مقادیر معیارهای کلید-مقدار. ترتیب مجموع متریک همان ترتیب متریک مشخص شده در درخواست است.
`dataTable`	`object`	یک شی جدول داده که می تواند با نمودارهای Google استفاده شود.
`dataTable.cols[]`	`list`	فهرستی از توصیفگرهای ستون برای ابعاد و به دنبال آن معیارها. ترتیب ابعاد و معیارها مانند مواردی است که از طریق پارامترهای `metrics` و `dimensions` در درخواست مشخص شده است. تعداد ستون ها تعداد ابعاد + تعداد معیارها است.
`dataTable.cols[].id`	`string`	شناسه ای که می تواند برای ارجاع به یک ستون خاص (به عنوان جایگزینی برای استفاده از نمایه های ستون) استفاده شود. برای تنظیم این مقدار از ID بعدی یا متریک استفاده می شود.
`dataTable.cols[].label`	`string`	برچسبی برای ستون (که ممکن است با تجسم نمایش داده شود). برای تنظیم این مقدار از ID بعدی یا متریک استفاده می شود.
`dataTable.cols[].type`	`string`	نوع داده برای این ستون.
`dataTable.rows[]`	`list`	ردیف‌های داده تجزیه و تحلیل در قالب جدول داده، که در آن هر ردیف یک شی است که حاوی فهرستی از مقادیر سلول برای ابعاد و به دنبال آن معیارها است. ترتیب ابعاد و معیارها همان است که در درخواست مشخص شده است. هر سلول فهرستی از N فیلد دارد که در آن N = تعداد ابعاد + تعداد معیارها.

کدهای خطا

در صورت موفقیت آمیز بودن درخواست، Core Reporting API یک کد وضعیت HTTP 200 را برمی گرداند. اگر در حین پردازش یک پرس و جو خطایی رخ دهد، API یک کد خطا و توضیحات را برمی گرداند. هر برنامه ای که از API تجزیه و تحلیل استفاده می کند، باید منطق مدیریت خطا را به درستی پیاده سازی کند. برای جزئیات بیشتر در مورد کدهای خطا و نحوه رسیدگی به آنها، راهنمای مرجع پاسخ به خطا را بخوانید.

آن را امتحان کنید!

می توانید پرس و جوهایی را در Core Reporting API امتحان کنید.

برای مشاهده ترکیبات معتبر معیارها و ابعاد در یک جستار، مقادیر نمونه پارامترها را در Query Explorer وارد کنید. نتایج پرس و جو نمونه به صورت جدولی با مقادیر برای تمام معیارها و ابعاد مشخص شده نشان داده شده است.
برای درخواست داده‌های زنده و دیدن پاسخ در قالب JSON، روش analytics.data.ga.get را در Google Data APIs Explorer امتحان کنید.

نمونه برداری

گوگل آنالیتیکس ترکیب خاصی از ابعاد و معیارها را در لحظه محاسبه می کند. برای بازگرداندن داده ها در یک زمان معقول، Google Analytics فقط ممکن است نمونه ای از داده ها را پردازش کند.

با تنظیم پارامتر samplingLevel می توانید سطح نمونه برداری را برای استفاده برای یک درخواست مشخص کنید.

اگر یک پاسخ Core Reporting API حاوی داده های نمونه برداری شده باشد، فیلد پاسخ containsSampledData true خواهد بود. علاوه بر این، 2 ویژگی اطلاعاتی در مورد سطح نمونه‌گیری برای پرس و جو ارائه می‌کنند: sampleSize و sampleSpace . با این 2 مقدار می توانید درصد جلساتی که برای پرس و جو استفاده شده است را محاسبه کنید. به عنوان مثال، اگر sampleSize 201,000 و sampleSpace 220,000 باشد، گزارش بر اساس (201,000 / 220,000) * 100 = 91.36٪ از جلسات است.

برای توضیح کلی نمونه گیری و نحوه استفاده از آن در گوگل آنالیتیکس به Sampling مراجعه کنید.

مدیریت نتایج داده های بزرگ

اگر انتظار دارید پرس و جو شما مجموعه نتایج بزرگی را برگرداند، از دستورالعمل های زیر استفاده کنید تا به شما کمک کند پرس و جوی API خود را بهینه کنید، از خطاها جلوگیری کنید و بیش از حد سهمیه را به حداقل برسانید. توجه داشته باشید که ما با مجاز کردن حداکثر 7 بعد و 10 معیار در هر درخواست API، یک خط پایه عملکرد تنظیم می‌کنیم. اگرچه پردازش برخی از پرس و جوهایی که تعداد زیادی معیار و ابعاد را مشخص می کنند ممکن است نسبت به سایرین بیشتر طول بکشد، محدود کردن تعداد معیارهای درخواستی ممکن است برای بهبود عملکرد پرس و جو کافی نباشد. در عوض، می توانید از تکنیک های زیر برای بهترین نتایج عملکرد استفاده کنید.

کاهش ابعاد در هر پرس و جو

API اجازه می دهد تا حداکثر 7 بعد را در هر درخواست مشخص کنید. بسیاری از اوقات، گوگل آنالیتیکس باید نتایج این پرس و جوهای پیچیده را در لحظه محاسبه کند. اگر تعداد ردیف‌های حاصل زیاد باشد، این امر می‌تواند زمان‌بر باشد. به عنوان مثال، جستجو برای کلمات کلیدی، بر اساس شهر به ساعت ممکن است با میلیون ها ردیف داده مطابقت داشته باشد. می‌توانید با کاهش تعداد ردیف‌هایی که Google Analytics باید پردازش کند، با محدود کردن تعداد ابعاد در جستجوی خود، عملکرد را بهبود بخشید.

تقسیم پرس و جو بر اساس محدوده تاریخ

به‌جای جستجو در نتایج کلیدی تاریخ در یک بازه تاریخ طولانی، هر بار یک هفته - یا حتی یک روز - درخواست‌های جداگانه تشکیل دهید. البته، برای یک مجموعه داده بزرگ، حتی یک درخواست برای داده های یک روزه ممکن است بیشتر از max-results باشد، در این صورت نمی توان از صفحه بندی اجتناب کرد. اما در هر صورت، اگر تعداد ردیف‌های منطبق برای درخواست شما از max-results بیشتر باشد، شکستن محدوده تاریخ ممکن است کل زمان بازیابی نتایج را کاهش دهد. این رویکرد می تواند عملکرد را در پرس و جوهای تک رشته ای و موازی بهبود بخشد.

صفحه بندی

صفحه‌بندی از طریق نتایج می‌تواند راهی مفید برای شکستن مجموعه‌های بزرگ نتایج به قطعات قابل مدیریت باشد. فیلد totalResults تعداد ردیف‌های منطبق را نشان می‌دهد و itemsPerPage حداکثر تعداد ردیف‌هایی را می‌دهد که می‌توان در نتیجه برگرداند. اگر نسبت totalResults به itemsPerPage زیاد باشد، ممکن است درخواست‌های فردی بیش از حد لازم طول بکشد. اگر فقط به تعداد محدودی ردیف نیاز دارید، مثلاً برای اهداف نمایشی، ممکن است برایتان مناسب باشد که یک محدودیت صریح در اندازه پاسخ را از طریق پارامتر max-results تعیین کنید. با این حال، اگر برنامه شما نیاز به پردازش مجموعه بزرگی از نتایج به طور کامل داشته باشد، ممکن است درخواست حداکثر ردیف های مجاز کارآمدتر باشد.

با استفاده از gzip

یک راه آسان و راحت برای کاهش پهنای باند مورد نیاز برای هر درخواست، فعال کردن فشرده‌سازی gzip است. اگرچه این امر به زمان اضافی CPU برای فشرده سازی نتایج نیاز دارد، معاوضه با هزینه های شبکه معمولاً آن را بسیار ارزشمند می کند. برای دریافت پاسخ کدگذاری شده با gzip، باید دو کار انجام دهید: یک هدر Accept-Encoding تنظیم کنید، و عامل کاربری خود را طوری تغییر دهید که شامل رشته gzip باشد. در اینجا نمونه ای از هدرهای HTTP که به درستی شکل گرفته اند برای فعال کردن فشرده سازی gzip آورده شده است:

Accept-Encoding: gzip
User-Agent: my program (gzip)

این سند مرجع کاملی برای پرس و جو و پاسخ برای Core Reporting API نسخه 3.0 ارائه می دهد.

معرفی

درخواست

API یک روش واحد برای درخواست داده ارائه می دهد:

analytics.data.ga.get()

API همچنین می تواند به عنوان یک نقطه پایانی REST-ful مورد جستجو قرار گیرد:

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/ga
  ?ids=ga:12345
  &start-date=2008-10-01
  &end-date=2008-10-31
  &metrics=ga:sessions,ga:bounces

هر پارامتر پرس و جو URL یک پارامتر پرس و جوی API را مشخص می کند که باید URL کدگذاری شده باشد .

خلاصه پارامترهای پرس و جو

نام	ارزش	ضروری	خلاصه
`ids`	`string`	آره	شناسه جدول منحصر به فرد فرم ga:XXXX، که در آن XXXX شناسه نمای آنالیتیکس (نمایه) است که پرس و جو داده ها را برای آن بازیابی می کند.
`start-date`	`string`	آره	تاریخ شروع برای واکشی داده های Analytics. درخواست‌ها می‌توانند تاریخ شروع را با فرمت `YYYY-MM-DD` یا به عنوان یک تاریخ نسبی (مثلاً `today` ، `yesterday` یا `NdaysAgo` که در آن `N` یک عدد صحیح مثبت است) تعیین کنند.
`end-date`	`string`	آره	تاریخ پایان برای واکشی داده های Analytics. درخواست می‌تواند تاریخ پایانی را با فرمت `YYYY-MM-DD` یا به عنوان یک تاریخ نسبی مشخص کند (به عنوان مثال، `today` ، `yesterday` یا `NdaysAgo` که در آن `N` یک عدد صحیح مثبت است).
`metrics`	`string`	آره	فهرستی از معیارهای جدا شده با کاما، مانند `ga:sessions,ga:bounces` .
`dimensions`	`string`	نه	فهرستی از ابعاد جدا شده با کاما برای داده های Analytics شما، مانند `ga:browser,ga:city` .
`sort`	`string`	نه	فهرستی از ابعاد و معیارهای جدا شده با کاما که ترتیب مرتب سازی و جهت مرتب سازی داده های برگشتی را نشان می دهد.
`filters`	`string`	نه	فیلترهای ابعاد یا متریک که داده های بازگردانده شده برای درخواست شما را محدود می کند.
`segment`	`string`	نه	داده های بازگردانده شده برای درخواست شما را بخش بندی می کند.
`samplingLevel`	`string`	نه	سطح نمونه گیری مورد نظر. مقادیر مجاز: `DEFAULT` - پاسخ را با اندازه نمونه برمی‌گرداند که سرعت و دقت را متعادل می‌کند. `FASTER` - پاسخ سریع با حجم نمونه کوچکتر را برمی گرداند. `HIGHER_PRECISION` - با استفاده از حجم نمونه بزرگ، پاسخ دقیق تری را نشان می دهد، اما ممکن است منجر به کندتر شدن پاسخ شود.
`include-empty-rows`	`boolean`	نه	پیش فرض ها به true; اگر روی false تنظیم شود، سطرهایی که تمام مقادیر متریک آنها صفر هستند از پاسخ حذف می شوند.
`start-index`	`integer`	نه	اولین ردیف داده برای بازیابی، از 1 شروع می شود. از این پارامتر به عنوان مکانیزم صفحه بندی همراه با پارامتر `max-results` استفاده کنید.
`max-results`	`integer`	نه	حداکثر تعداد ردیف هایی که باید در پاسخ گنجانده شود.
`output`	`string`	نه	نوع خروجی مورد نظر برای داده های Analytics که در پاسخ بازگردانده شده است. مقادیر قابل قبول `json` و `dataTable` هستند. پیش فرض: `json` .
`fields`	`string`	نه	انتخابگر که زیر مجموعه ای از فیلدها را برای درج در پاسخ مشخص می کند.
`prettyPrint`	`string`	نه	پاسخ را با تورفتگی و شکستگی برمی‌گرداند. `false` پیش فرض
`userIp`	`string`	نه	آدرس IP کاربر نهایی را که تماس API برای او انجام می شود را مشخص می کند. برای سقف استفاده در هر IP استفاده می شود.
`quotaUser`	`string`	نه	جایگزینی برای userIp در مواردی که آدرس IP کاربر ناشناخته است.
`access_token`	`string`	نه	یکی از راه های ممکن برای ارائه توکن OAuth 2.0 .
`callback`	`string`	نه	نام تابع فراخوانی جاوا اسکریپت که پاسخ را مدیریت می کند. در درخواست های جاوا اسکریپت JSON-P استفاده می شود.
`key`	`string`	نه	برای مجوز OAuth 1.0a برای تعیین برنامه شما برای دریافت سهمیه استفاده می شود. به عنوان مثال: `key= AldefliuhSFADSfasdfasdfASdf` .

جزئیات پارامتر پرس و جو

شناسه

ids= ga:12345

ضروری.

تاریخ شروع

start-date= 2009-04-20

ضروری.

اولین start-date معتبر 2005-01-01 است. محدودیت بالایی برای تاریخ شروع وجود ندارد.

نمونه محدوده تاریخ برای 7 روز گذشته (از دیروز) با استفاده از تاریخ های نسبی:

  &start-date=7daysAgo
  &end-date=yesterday

تاریخ پایان

end-date= 2009-05-20

ضروری.

اولین end-date معتبر 2005-01-01 است. محدودیت بالایی برای end-date وجود ندارد.

نمونه محدوده تاریخ برای 10 روز گذشته (از امروز) با استفاده از تاریخ های نسبی:

  &start-date=9daysAgo
  &end-date=today

ابعاد

dimensions= ga:browser,ga:city

اختیاری.

هنگام استفاده از dimensions در درخواست داده، از محدودیت های زیر آگاه باشید:

شما می توانید حداکثر 7 بعد را در هر پرس و جو ارائه کنید.
شما نمی توانید درخواستی را ارسال کنید که فقط از ابعاد تشکیل شده باشد: باید هر ابعاد درخواستی را با حداقل یک متریک ترکیب کنید.
فقط برخی از ابعاد را می توان در همان پرس و جو جستجو کرد. از ابزار ترکیبی معتبر در مرجع ابعاد و متریک استفاده کنید تا ببینید کدام ابعاد را می توان با هم استفاده کرد.

معیارهای

metrics= ga:sessions,ga:bounces

ضروری.

هر درخواستی باید حداقل یک متریک ارائه کند. یک درخواست نمی تواند فقط شامل ابعاد باشد.
شما می توانید حداکثر 10 معیار برای هر پرس و جو ارائه کنید.
اکثر ترکیبات معیارهای چند دسته را می توان با هم استفاده کرد، مشروط بر اینکه هیچ ابعادی مشخص نشده باشد.
یک متریک را می توان در ترکیب با سایر ابعاد یا معیارها استفاده کرد، اما فقط در مواردی که ترکیبات معتبر برای آن معیار اعمال می شود. برای جزئیات به مرجع ابعاد و متریک مراجعه کنید.

مرتب سازی

sort= ga:country,ga:browser

اختیاری.

فهرستی از معیارها و ابعاد که ترتیب مرتب سازی و جهت مرتب سازی داده های برگشتی را نشان می دهد.

ترتیب مرتب سازی با ترتیب از چپ به راست معیارها و ابعاد فهرست شده مشخص می شود.
جهت مرتب سازی به طور پیش فرض صعودی است و می توان آن را با استفاده از پیشوند علامت منفی ( - ) در فیلد درخواستی به نزولی تغییر داد.

sort=ga:country,ga:browser

sort=ga:browser,ga:country

هنگام استفاده از پارامتر sort ، موارد زیر را در نظر داشته باشید:

فقط بر اساس ابعاد یا مقادیر معیارهایی که در dimensions یا پارامترهای metrics استفاده کرده اید مرتب کنید. اگر درخواست شما در فیلدی که در پارامتر ابعاد یا متریک مشخص نشده است مرتب شود، یک خطا دریافت خواهید کرد.
به‌طور پیش‌فرض، رشته‌ها به ترتیب حروف الفبای صعودی در محلی en-US مرتب می‌شوند.
اعداد به طور پیش فرض به ترتیب عددی صعودی مرتب شده اند.
تاریخ ها به طور پیش فرض بر اساس تاریخ به ترتیب صعودی مرتب شده اند.

فیلترها

filters=ga:medium%3D%3Dreferral

نحو فیلتر
اپراتورهای فیلتر
عبارات فیلتر
ترکیب فیلترها
- اپراتور OR
- و اپراتور

اختیاری.

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

رمزگذاری URL : کتابخانه های سرویس گیرنده Google API به طور خودکار اپراتورهای فیلتر را رمزگذاری می کنند.
فیلتر ابعاد : فیلتر قبل از انباشته شدن هر یک از ابعاد اتفاق می‌افتد، به طوری که معیارهای برگشتی مجموع را فقط برای ابعاد مربوطه نشان می‌دهد. در مثال بالا، تعداد بازدید از صفحه فقط همان بازدیدهایی است که مرورگر فایرفاکس است.
فیلتر معیارها : فیلتر کردن معیارها پس از جمع‌آوری معیارها انجام می‌شود.
ترکیب‌های معتبر : می‌توانید برای یک بعد یا معیاری که بخشی از درخواست شما نیست فیلتر کنید، مشروط بر اینکه همه ابعاد/متریک‌های موجود در درخواست و فیلتر ترکیب‌های معتبری باشند. به عنوان مثال، ممکن است بخواهید فهرستی از تاریخ بازدید از صفحه را جستجو کنید و در یک مرورگر خاص فیلتر کنید. برای اطلاعات بیشتر به مرجع ابعاد و متریک مراجعه کنید.

نحو فیلتر

یک فیلتر واحد از فرم زیر استفاده می کند:

ga:name operator expression

در این نحو:

name - نام بعد یا متریک برای فیلتر کردن. به عنوان مثال: فیلترهای ga:pageviews در متریک بازدید از صفحه.
اپراتور - نوع تطبیق فیلتر را برای استفاده تعریف می کند. اپراتورها به ابعاد یا معیارها اختصاص دارند.
بیان - مقادیری را که باید در نتایج گنجانده شوند یا از نتایج حذف شوند را بیان می کند. عبارات از نحو عبارت منظم استفاده می کنند.

اپراتورهای فیلتر

**فیلترهای متریک**
اپراتور	شرح	فرم رمزگذاری شده URL	مثال ها
`==`	برابر است	`%3D%3D`	نتایج را در جایی که زمان در صفحه دقیقاً ده ثانیه است برگردانید: `filters=ga:timeOnPage%3D%3D10`
`!=`	برابر نیست	`!%3D`	نتایج را در جایی که زمان در صفحه ده ثانیه نیست برگردانید: `filters=ga:timeOnPage!%3D10`
`>`	بزرگتر از	`%3E`	نتایج را در جایی برگردانید که زمان در صفحه به شدت بیشتر از ده ثانیه باشد: `filters=ga:timeOnPage%3E10`
`<`	کمتر از	`%3C`	نتایج را در جایی که زمان در صفحه به طور دقیق کمتر از ده ثانیه است برگردانید: `filters=ga:timeOnPage%3C10`
`>=`	بزرگتر یا مساوی با	`%3E%3D`	نتایج را در جایی که زمان در صفحه ده ثانیه یا بیشتر است برگردانید: `filters=ga:timeOnPage%3E%3D10`
`<=`	کمتر یا مساوی با	`%3C%3D`	نتایج را در جایی که زمان در صفحه ده ثانیه یا کمتر است برگردانید: `filters=ga:timeOnPage%3C%3D10`

**فیلترهای ابعاد**
اپراتور	شرح	فرم رمزگذاری شده URL	مثال
`==`	مطابقت کامل	`%3D%3D`	معیارهای مجموع جایی که شهر ایروین است: `filters=ga:city%3D%3DIrvine`
`!=`	مطابقت ندارد	`!%3D`	معیارهای مجموع در جایی که شهر ایروین نیست : `filters=ga:city!%3DIrvine`
`=@`	حاوی رشته فرعی	`%3D@`	معیارهای انبوه در جایی که شهر حاوی یورک است: `filters=ga:city%3D@York`
`!@`	شامل رشته فرعی نیست	`!@`	معیارهای مجموع در جایی که شهر شامل یورک نیست: `filters=ga:city!@York`
`=~`	شامل یک مسابقه برای عبارت منظم است	`%3D~`	معیارهای انبوه جایی که شهر با New شروع می شود: `filters=ga:city%3D~%5ENew.*` (%5E URL کدگذاری شده از کاراکتر ^ است که یک الگو را به ابتدای رشته متصل می کند.)
`!~`	با عبارت منظم مطابقت ندارد	`!~`	معیارهای انبوه در جایی که شهر با New شروع نمی شود: `filters=ga:city!~%5ENew.*`

عبارات فیلتر

چند قانون مهم برای عبارات فیلتر وجود دارد:

کاراکترهای رزرو شده توسط URL - کاراکترهایی مانند & باید به روش معمول با URL کدگذاری شوند.
کاراکترهای رزرو شده - هنگامی که در یک عبارت ظاهر می شوند، نقطه ویرگول و کاما باید به صورت بک اسلش خارج شوند:
- نقطه ویرگول \;
- کاما \,
عبارات منظم - همچنین می توانید از عبارات منظم در عبارات فیلتر با استفاده از عملگرهای =~ و !~ استفاده کنید. نحو آنها شبیه عبارات منظم پرل است و این قوانین اضافی را دارد:
- حداکثر طول 128 کاراکتر - عبارات معمولی بیش از 128 کاراکتر منجر به 400 Bad Request از سرور می شود.
- حساسیت به حروف کوچک و بزرگ - تطبیق عبارت منظم به حروف بزرگ و کوچک حساس نیست.

ترکیب فیلترها

یا

مثال‌ها: (هر کدام باید URL کدگذاری شده باشند)

کشور یکی است (ایالات متحده یا کانادا):
ga:country==United%20States,ga:country==Canada

کاربران فایرفاکس در سیستم عامل (ویندوز یا مکینتاش):
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

و

مثال‌ها: (هر کدام باید URL کدگذاری شده باشند)

کشور ایالات متحده و مرورگر فایرفاکس است:
ga:country==United%20States;ga:browser==Firefox

کشور ایالات متحده است و زبان با 'en' شروع نمی شود:
ga:country==United%20States;ga:language!~^en.*

کشور ایالات متحده است و تعداد جلسات بیشتر از 5 است:
ga:country==United%20States;ga:sessions>5

بخش

segment=gaid::-10
 segment=sessions::condition::ga:medium%3D%3Dreferral
 segment=users::condition::ga:browser%3D%3DChrome

اختیاری.

برای جزئیات کامل در مورد نحوه درخواست یک بخش در Core Reporting API به راهنمای توسعه بخش Segments مراجعه کنید.

برای یک نمای کلی مفهومی از بخش‌ها، به بخش مرجع و بخش‌های ویژگی در مرکز راهنمایی مراجعه کنید.

توجه : پیشوند dynamic:: از تاریخ 27 مارس 2014 منسوخ شده است. توصیه می شود در اسرع وقت به نحو جدید مهاجرت کنید.

samplingLevel

samplingLevel=DEFAULT

اختیاری.

DEFAULT - پاسخ را با اندازه نمونه برمی‌گرداند که سرعت و دقت را متعادل می‌کند.
FASTER - پاسخ سریع با حجم نمونه کوچکتر را برمی گرداند.
HIGHER_PRECISION - با استفاده از حجم نمونه بزرگ، پاسخ دقیق تری را نشان می دهد، اما ممکن است منجر به کندتر شدن پاسخ شود.

در صورت عدم ارائه، از سطح نمونه گیری DEFAULT استفاده خواهد شد.

برای جزئیات نحوه محاسبه درصد جلساتی که برای یک پرس و جو استفاده شده است، به بخش Sampling مراجعه کنید.

شامل-خالی-ردیف ها

include-empty-rows=true

اختیاری.

شروع-شاخص

start-index=10

اختیاری.

حداکثر نتایج

max-results=100

اختیاری.

خروجی

output=dataTable

اختیاری.

json - ویژگی rows پیش فرض را در پاسخ، حاوی یک شی JSON، خروجی می دهد.
dataTable - یک ویژگی dataTable را در پاسخ خروجی می دهد که حاوی یک شی جدول داده است. این شی Data Table می توان مستقیماً با تجسم نمودارهای Google استفاده کرد.

اگر ارائه نشده باشد، از پاسخ پیش‌فرض JSON استفاده خواهد شد.

زمینه های

fields=rows,columnHeaders(name,dataType)

اختیاری.

فرمت مقدار پارامتر درخواست فیلدها بر اساس نحو XPath است. نحو پشتیبانی شده در زیر خلاصه شده است.

از یک لیست جدا شده با کاما برای انتخاب چندین فیلد استفاده کنید.
از a/b برای انتخاب فیلد b که در فیلد a تودرتو است استفاده کنید. از a/b/c برای انتخاب یک فیلد c تو در تو در b استفاده کنید.
از یک انتخابگر فرعی برای درخواست مجموعه ای از فیلدهای فرعی خاص از آرایه ها یا اشیاء با قرار دادن عبارات در پرانتز "( )" استفاده کنید.
به عنوان مثال: fields=columnHeaders(name,dataType) فقط فیلدهای name و dataType را در آرایه columnHeaders برمی گرداند. شما همچنین می توانید یک زیر فیلد را مشخص کنید که در آن fields=columnHeader(name) معادل fields=columnHeader/name باشد.

زیبا پرینت

prettyPrint=false

اختیاری.

اگر true ، پاسخ را در قالبی قابل خواندن برای انسان برمی‌گرداند. مقدار پیش فرض: false .

quotaUser

quotaUser=4kh4r2h4

اختیاری.

اگر هر دو ارائه شده باشند، این userIp را لغو می کند.

واکنش

JSON

{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "include-empty-rows": boolean
    "samplingLevel": string,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

فیلدهای پاسخ

خواص ساختار بدن پاسخ به شرح زیر تعریف می شود:

نام ملک	ارزش	شرح
`kind`	`string`	نوع منبع مقدار "analytics#gaData" است.
`id`	`string`	شناسه ای برای این پاسخ داده.
`query`	`object`	این شی شامل تمام مقادیر ارسال شده به عنوان پارامتر به پرس و جو است. معنی هر فیلد در توضیح پارامتر پرس و جوی مربوطه آن توضیح داده شده است.
`query.start-date`	`string`	تاریخ شروع.
`query.end-date`	`string`	تاریخ پایان.
`query.ids`	`string`	شناسه جدول منحصر به فرد
`query.dimensions[]`	`list`	فهرست ابعاد تجزیه و تحلیل
`query.metrics[]`	`list`	فهرست معیارهای تحلیلی
`query.samplingLevel`	`string`	`Requested sampling level.`
`query.include-empty-rows`	`boolean`	پیش فرض ها به true; اگر روی false تنظیم شود، سطرهایی که تمام مقادیر متریک آنها صفر هستند از پاسخ حذف می شوند.
`query.sort[]`	`list`	فهرست معیارها یا ابعادی که داده ها بر اساس آنها مرتب شده اند.
`query.filters`	`string`	فهرست فیلترهای متریک یا ابعاد جدا شده با کاما.
`query.segment`	`string`	بخش تجزیه و تحلیل.
`query.start-index`	`integer`	فهرست شروع.
`query.max-results`	`integer`	حداکثر نتایج در هر صفحه
`startIndex`	`integer`	شاخص شروع سطرها که توسط پارامتر جستجوی `start-index` مشخص شده است. مقدار پیش فرض 1 است.
`itemsPerPage`	`integer`	حداکثر تعداد ردیف‌هایی که پاسخ می‌تواند داشته باشد، صرف‌نظر از تعداد واقعی ردیف‌های برگشتی. اگر پارامتر query `max-results` مشخص شده باشد، مقدار `itemsPerPage` کوچکتر از `max-results` یا 10000 است. مقدار پیش فرض `itemsPerPage` 1000 است.
`totalResults`	`integer`	تعداد کل ردیف ها در نتیجه پرس و جو، صرف نظر از تعداد ردیف های برگشت داده شده در پاسخ. برای جستارهایی که منجر به تعداد زیادی ردیف می شود، `totalResults` می تواند بزرگتر از `itemsPerPage` باشد. برای توضیحات بیشتر در مورد `totalResults` و `itemsPerPage` برای جستارهای بزرگ به صفحه بندی مراجعه کنید.
`startDate`	`string`	تاریخ شروع برای پرس و جو داده، همانطور که توسط پارامتر `start-date` مشخص شده است.
`endDate`	`string`	تاریخ پایان برای درخواست داده، همانطور که توسط پارامتر `end-date` مشخص شده است.
`selfLink`	`string`	پیوند به این صفحه از نتایج برای این پرسش داده.
`previousLink`	`string`	پیوند به صفحه قبلی نتایج برای این پرسش داده.
`nextLink`	`string`	پیوند به صفحه بعدی نتایج برای این پرسش داده.
`profileInfo`	`object`	اطلاعات مربوط به نمای (نمایه) که داده برای آن درخواست شده است. اطلاعات مشاهده (نمایه) از طریق API مدیریت Google Analytics در دسترس است.
`profileInfo.profileId`	`string`	مشاهده شناسه (نمایه)، مانند `1174` .
`profileInfo.accountId`	`string`	شناسه حسابی که این نما (نمایه) به آن تعلق دارد، مانند `30481` .
`profileInfo.webPropertyId`	`string`	شناسه دارایی وب که این نما (نمایه) به آن تعلق دارد، مانند `UA-30481-1` .
`profileInfo.internalWebPropertyId`	`string`	شناسه داخلی ویژگی وب که این نما (نمایه) به آن تعلق دارد، مانند `UA-30481-1` .
`profileInfo.profileName`	`string`	نام نما (نمایه).
`profileInfo.tableId`	`string`	شناسه جدول برای مشاهده (نمایه)، متشکل از "ga:" و سپس شناسه نمایش (نمایه).
`containsSampledData`	`boolean`	اگر پاسخ حاوی داده های نمونه برداری شده باشد درست است.
`sampleSize`	`string`	تعداد نمونه های مورد استفاده برای محاسبه داده های نمونه برداری شده .
`sampleSpace`	`string`	اندازه کل فضای نمونه برداری این نشان دهنده حجم کل فضای نمونه موجود است که نمونه ها از آن انتخاب شده اند.
`columnHeaders[]`	`list`	سرصفحه‌های ستونی که نام ابعاد را به دنبال نام متریک فهرست می‌کنند. ترتیب ابعاد و معیارها مانند مواردی است که از طریق پارامترهای `metrics` و `dimensions` در درخواست مشخص شده است. تعداد هدرها تعداد ابعاد + تعداد معیارها است.
`columnHeaders[].name`	`string`	نام بعد یا متریک.
`columnHeaders[].columnType`	`string`	نوع ستون. یا "DIMENSION" یا "METRIC".
`columnHeaders[].dataType`	`string`	نوع داده. سرصفحه های ستون ابعاد فقط `STRING` به عنوان نوع داده دارند. سرصفحه های ستون متریک دارای انواع داده برای مقادیر متریک مانند `INTEGER` ، `PERCENT` ، `TIME` ، `CURRENCY` ، `FLOAT` ، و غیره هستند. پاسخ API فراداده را برای همه انواع داده های ممکن مشاهده کنید.
`totalsForAllResults`	`object`	مجموع مقادیر برای معیارهای درخواستی به عنوان جفت نام‌ها و مقادیر معیارهای کلید-مقدار. ترتیب مجموع متریک همان ترتیب متریک مشخص شده در درخواست است.
`rows[]`	`list`	ردیف های داده تجزیه و تحلیل، که در آن هر ردیف حاوی لیستی از مقادیر ابعاد و به دنبال آن مقادیر متریک است. ترتیب ابعاد و معیارها همان است که در درخواست مشخص شده است. هر ردیف فهرستی از N فیلد دارد که در آن N = تعداد ابعاد + تعداد معیارها.

JSON (جدول داده)

{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "samplingLevel": string,
    "include-empty-rows": boolean,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "dataTable": {
    "cols": [
      {
        "id": string,
        "label": string,
        "type": string
      }
    ],
    "rows": [
      {
        "c": [
          {    
            "v": string
          }
        ]
      }   
    ]
  },
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

فیلدهای پاسخ

خواص ساختار بدن پاسخ به شرح زیر تعریف می شود:

نام ملک	ارزش	شرح
`kind`	`string`	نوع منبع مقدار "analytics#gaData" است.
`id`	`string`	شناسه ای برای این پاسخ داده.
`query`	`object`	این شی شامل تمام مقادیر ارسال شده به عنوان پارامتر به پرس و جو است. معنی هر فیلد در توضیح پارامتر پرس و جوی مربوطه آن توضیح داده شده است.
`query.start-date`	`string`	تاریخ شروع.
`query.end-date`	`string`	تاریخ پایان.
`query.ids`	`string`	شناسه جدول منحصر به فرد
`query.dimensions[]`	`list`	فهرست ابعاد تجزیه و تحلیل
`query.metrics[]`	`list`	فهرست معیارهای تحلیلی
`query.samplingLevel`	`string`	`Requested sampling level.`
`query.include-empty-rows`	`boolean`	پیش فرض ها به true; اگر روی false تنظیم شود، سطرهایی که تمام مقادیر متریک آنها صفر هستند از پاسخ حذف می شوند.
`query.sort[]`	`list`	فهرست معیارها یا ابعادی که داده ها بر اساس آنها مرتب شده اند.
`query.filters`	`string`	فهرست فیلترهای متریک یا ابعاد جدا شده با کاما.
`query.segment`	`string`	بخش تجزیه و تحلیل.
`query.start-index`	`integer`	فهرست شروع.
`query.max-results`	`integer`	حداکثر نتایج در هر صفحه
`startIndex`	`integer`	شاخص شروع سطرها که توسط پارامتر جستجوی `start-index` مشخص شده است. مقدار پیش فرض 1 است.
`itemsPerPage`	`integer`	حداکثر تعداد ردیف‌هایی که پاسخ می‌تواند داشته باشد، صرف‌نظر از تعداد واقعی ردیف‌های برگشتی. اگر پارامتر query `max-results` مشخص شده باشد، مقدار `itemsPerPage` کوچکتر از `max-results` یا 10000 است. مقدار پیش فرض `itemsPerPage` 1000 است.
`totalResults`	`integer`	تعداد کل ردیف ها در نتیجه پرس و جو، صرف نظر از تعداد ردیف های برگشت داده شده در پاسخ. برای جستارهایی که منجر به تعداد زیادی ردیف می شود، `totalResults` می تواند بزرگتر از `itemsPerPage` باشد. برای توضیحات بیشتر در مورد `totalResults` و `itemsPerPage` برای جستارهای بزرگ به صفحه بندی مراجعه کنید.
`startDate`	`string`	تاریخ شروع برای پرس و جو داده، همانطور که توسط پارامتر `start-date` مشخص شده است.
`endDate`	`string`	تاریخ پایان برای درخواست داده، همانطور که توسط پارامتر `end-date` مشخص شده است.
`selfLink`	`string`	پیوند به این صفحه از نتایج برای این پرسش داده.
`previousLink`	`string`	پیوند به صفحه قبلی نتایج برای این پرسش داده.
`nextLink`	`string`	پیوند به صفحه بعدی نتایج برای این پرسش داده.
`profileInfo`	`object`	اطلاعات مربوط به نمای (نمایه) که داده برای آن درخواست شده است. اطلاعات مشاهده (نمایه) از طریق API مدیریت Google Analytics در دسترس است.
`profileInfo.profileId`	`string`	مشاهده شناسه (نمایه)، مانند `1174` .
`profileInfo.accountId`	`string`	شناسه حسابی که این نما (نمایه) به آن تعلق دارد، مانند `30481` .
`profileInfo.webPropertyId`	`string`	شناسه دارایی وب که این نما (نمایه) به آن تعلق دارد، مانند `UA-30481-1` .
`profileInfo.internalWebPropertyId`	`string`	شناسه داخلی ویژگی وب که این نما (نمایه) به آن تعلق دارد، مانند `UA-30481-1` .
`profileInfo.profileName`	`string`	نام نما (نمایه).
`profileInfo.tableId`	`string`	شناسه جدول برای مشاهده (نمایه)، متشکل از "ga:" و سپس شناسه نمایش (نمایه).
`containsSampledData`	`boolean`	اگر پاسخ حاوی داده های نمونه برداری شده باشد درست است.
`sampleSize`	`string`	تعداد نمونه های مورد استفاده برای محاسبه داده های نمونه برداری شده .
`sampleSpace`	`string`	اندازه کل فضای نمونه برداری این نشان دهنده حجم کل فضای نمونه موجود است که نمونه ها از آن انتخاب شده اند.
`columnHeaders[]`	`list`	سرصفحه‌های ستونی که نام ابعاد را به دنبال نام متریک فهرست می‌کنند. ترتیب ابعاد و معیارها مانند مواردی است که از طریق پارامترهای `metrics` و `dimensions` در درخواست مشخص شده است. تعداد هدرها تعداد ابعاد + تعداد معیارها است.
`columnHeaders[].name`	`string`	نام بعد یا متریک.
`columnHeaders[].columnType`	`string`	نوع ستون. یا "DIMENSION" یا "METRIC".
`columnHeaders[].dataType`	`string`	نوع داده. سرصفحه های ستون ابعاد فقط `STRING` به عنوان نوع داده دارند. سرصفحه های ستون متریک دارای انواع داده برای مقادیر متریک مانند `INTEGER` ، `PERCENT` ، `TIME` ، `CURRENCY` ، `FLOAT` ، و غیره هستند. پاسخ API فراداده را برای همه انواع داده های ممکن مشاهده کنید.
`totalsForAllResults`	`object`	مجموع مقادیر برای معیارهای درخواستی به عنوان جفت نام‌ها و مقادیر معیارهای کلید-مقدار. ترتیب مجموع متریک همان ترتیب متریک مشخص شده در درخواست است.
`dataTable`	`object`	یک شی جدول داده که می تواند با نمودارهای Google استفاده شود.
`dataTable.cols[]`	`list`	فهرستی از توصیفگرهای ستون برای ابعاد و به دنبال آن معیارها. ترتیب ابعاد و معیارها مانند مواردی است که از طریق پارامترهای `metrics` و `dimensions` در درخواست مشخص شده است. تعداد ستون ها تعداد ابعاد + تعداد معیارها است.
`dataTable.cols[].id`	`string`	شناسه ای که می تواند برای ارجاع به یک ستون خاص (به عنوان جایگزینی برای استفاده از نمایه های ستون) استفاده شود. برای تنظیم این مقدار از ID بعدی یا متریک استفاده می شود.
`dataTable.cols[].label`	`string`	برچسبی برای ستون (که ممکن است با تجسم نمایش داده شود). برای تنظیم این مقدار از ID بعدی یا متریک استفاده می شود.
`dataTable.cols[].type`	`string`	نوع داده برای این ستون.
`dataTable.rows[]`	`list`	ردیف‌های داده تجزیه و تحلیل در قالب جدول داده، که در آن هر ردیف یک شی است که حاوی فهرستی از مقادیر سلول برای ابعاد و به دنبال آن معیارها است. ترتیب ابعاد و معیارها همان است که در درخواست مشخص شده است. هر سلول فهرستی از N فیلد دارد که در آن N = تعداد ابعاد + تعداد معیارها.

کدهای خطا

آن را امتحان کنید!

می توانید پرس و جوهایی را در Core Reporting API امتحان کنید.

برای مشاهده ترکیبات معتبر معیارها و ابعاد در یک جستار، مقادیر نمونه پارامترها را در Query Explorer وارد کنید. نتایج پرس و جو نمونه به صورت جدولی با مقادیر برای تمام معیارها و ابعاد مشخص شده نشان داده شده است.
برای درخواست داده‌های زنده و دیدن پاسخ در قالب JSON، روش analytics.data.ga.get را در Google Data APIs Explorer امتحان کنید.

نمونه برداری

با تنظیم پارامتر samplingLevel می توانید سطح نمونه برداری را برای استفاده برای یک درخواست مشخص کنید.

برای توضیح کلی نمونه گیری و نحوه استفاده از آن در گوگل آنالیتیکس به Sampling مراجعه کنید.

مدیریت نتایج داده های بزرگ

کاهش ابعاد در هر پرس و جو

تقسیم پرس و جو بر اساس محدوده تاریخ

صفحه بندی

با استفاده از gzip

Accept-Encoding: gzip
User-Agent: my program (gzip)