این سند مرجع کاملی برای پرس و جو و پاسخ برای 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 | نه | سطح نمونه گیری مورد نظر. مقادیر مجاز:
|
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
ga:
با شناسه نمای (نمایه) Analytics است. میتوانید شناسه view (نمایه) را با استفاده از روش analytics.management.profiles.list
، که id
در منبع View (نمایه) در API مدیریت Google Analytics ارائه میکند، بازیابی کنید.تاریخ شروع
start-date= 2009-04-20
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
start-date
و end-date
در درخواست وارد نکنید، سرور یک خطا را برمیگرداند. مقادیر تاریخ می توانند برای یک تاریخ خاص با استفاده از الگوی YYYY-MM-DD
یا نسبی با استفاده از today
، yesterday
یا الگوی NdaysAgo
باشند. مقادیر باید با [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
مطابقت داشته باشند.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
پارامتر رشته پرس و جو 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
از سرور می شود. - حساسیت به حروف کوچک و بزرگ - تطبیق عبارت منظم به حروف بزرگ و کوچک حساس نیست.
- حداکثر طول 128 کاراکتر - عبارات معمولی بیش از 128 کاراکتر منجر به
ترکیب فیلترها
فیلترها را می توان با استفاده از منطق بولی 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 مراجعه کنید.
برای یک نمای کلی مفهومی از بخشها، به بخش مرجع و بخشهای ویژگی در مرکز راهنمایی مراجعه کنید.
ابعاد و معیارهای مجاز در بخشها.
همه ابعاد و معیارها را نمی توان در بخش ها استفاده کرد. برای بررسی ابعاد و معیارهای مجاز در بخشها از کاوشگر ابعاد و متریک دیدن کنید.
samplingLevel
samplingLevel=DEFAULT
-
DEFAULT
- پاسخ را با اندازه نمونه برمیگرداند که سرعت و دقت را متعادل میکند. -
FASTER
- پاسخ سریع با حجم نمونه کوچکتر را برمی گرداند. -
HIGHER_PRECISION
- با استفاده از حجم نمونه بزرگ، پاسخ دقیق تری را نشان می دهد، اما ممکن است منجر به کندتر شدن پاسخ شود.
DEFAULT
استفاده خواهد شد.شامل-خالی-ردیف ها
include-empty-rows=true
شروع-شاخص
start-index=10
1
است. (شاخصهای نتایج بر اساس 1 هستند. یعنی ردیف اول ردیف 1
است نه ردیف 0
) از این پارامتر به عنوان مکانیزم صفحهبندی به همراه پارامتر max-results
برای موقعیتهایی استفاده کنید که totalResults
از 10000 فراتر میرود و میخواهید ردیفهای نمایهشده را بازیابی کنید. در 10001 و بالاتر.حداکثر نتایج
max-results=100
start-index
برای بازیابی زیرمجموعهای از عناصر استفاده کنید، یا از آن به تنهایی برای محدود کردن تعداد عناصر بازگشتی استفاده کنید، از اول شروع کنید. اگر max-results
ارائه نشود، پرس و جو حداکثر 1000 ردیف را برمی گرداند.ga:country
وجود دارد، بنابراین هنگام تقسیم بندی فقط بر اساس کشور، نمی توانید بیش از 300 ردیف دریافت کنید، حتی اگر max-results
روی یک مقدار بالاتر تنظیم کنید.خروجی
output=dataTable
-
json
- ویژگیrows
پیش فرض را در پاسخ، حاوی یک شی JSON، خروجی می دهد. -
dataTable
- یک ویژگیdataTable
را در پاسخ خروجی می دهد که حاوی یک شی جدول داده است. این شیData Table
می توان مستقیماً با تجسم نمودارهای Google استفاده کرد.
زمینه های
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 توضیح داده شده است، اگر تعداد کل نتایج از اندازه صفحه برای پاسخ فعلی بیشتر باشد، می توانند متفاوت باشند.
{
"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 = تعداد ابعاد + تعداد معیارها. |
{
"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 ارائه می دهد.
معرفی
شما از 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 | نه | سطح نمونه گیری مورد نظر. مقادیر مجاز:
|
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
ga:
با شناسه نمای (نمایه) Analytics است. میتوانید شناسه view (نمایه) را با استفاده از روش analytics.management.profiles.list
، که id
در منبع View (نمایه) در API مدیریت Google Analytics ارائه میکند، بازیابی کنید.تاریخ شروع
start-date= 2009-04-20
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
start-date
و end-date
در درخواست وارد نکنید، سرور یک خطا را برمیگرداند. مقادیر تاریخ می توانند برای یک تاریخ خاص با استفاده از الگوی YYYY-MM-DD
یا نسبی با استفاده از today
، yesterday
یا الگوی NdaysAgo
باشند. مقادیر باید با [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
مطابقت داشته باشند.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
پارامتر رشته پرس و جو 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
از سرور می شود. - حساسیت به حروف کوچک و بزرگ - تطبیق عبارت منظم به حروف بزرگ و کوچک حساس نیست.
- حداکثر طول 128 کاراکتر - عبارات معمولی بیش از 128 کاراکتر منجر به
ترکیب فیلترها
فیلترها را می توان با استفاده از منطق بولی 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 مراجعه کنید.
برای یک نمای کلی مفهومی از بخشها، به بخش مرجع و بخشهای ویژگی در مرکز راهنمایی مراجعه کنید.
ابعاد و معیارهای مجاز در بخشها.
همه ابعاد و معیارها را نمی توان در بخش ها استفاده کرد. برای بررسی ابعاد و معیارهای مجاز در بخشها از کاوشگر ابعاد و متریک دیدن کنید.
samplingLevel
samplingLevel=DEFAULT
-
DEFAULT
- پاسخ را با اندازه نمونه برمیگرداند که سرعت و دقت را متعادل میکند. -
FASTER
- پاسخ سریع با حجم نمونه کوچکتر را برمی گرداند. -
HIGHER_PRECISION
- با استفاده از حجم نمونه بزرگ، پاسخ دقیق تری را نشان می دهد، اما ممکن است منجر به کندتر شدن پاسخ شود.
DEFAULT
استفاده خواهد شد.شامل-خالی-ردیف ها
include-empty-rows=true
شروع-شاخص
start-index=10
1
است. (شاخصهای نتایج بر اساس 1 هستند. یعنی ردیف اول ردیف 1
است نه ردیف 0
) از این پارامتر به عنوان مکانیزم صفحهبندی به همراه پارامتر max-results
برای موقعیتهایی استفاده کنید که totalResults
از 10000 فراتر میرود و میخواهید ردیفهای نمایهشده را بازیابی کنید. در 10001 و بالاتر.حداکثر نتایج
max-results=100
start-index
برای بازیابی زیرمجموعهای از عناصر استفاده کنید، یا از آن به تنهایی برای محدود کردن تعداد عناصر بازگشتی استفاده کنید، از اول شروع کنید. اگر max-results
ارائه نشود، پرس و جو حداکثر 1000 ردیف را برمی گرداند.ga:country
وجود دارد، بنابراین هنگام تقسیم بندی فقط بر اساس کشور، نمی توانید بیش از 300 ردیف دریافت کنید، حتی اگر max-results
روی یک مقدار بالاتر تنظیم کنید.خروجی
output=dataTable
-
json
- ویژگیrows
پیش فرض را در پاسخ، حاوی یک شی JSON، خروجی می دهد. -
dataTable
- یک ویژگیdataTable
را در پاسخ خروجی می دهد که حاوی یک شی جدول داده است. این شیData Table
می توان مستقیماً با تجسم نمودارهای Google استفاده کرد.
زمینه های
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 توضیح داده شده است، اگر تعداد کل نتایج از اندازه صفحه برای پاسخ فعلی بیشتر باشد، می توانند متفاوت باشند.
{
"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 = تعداد ابعاد + تعداد معیارها. |
{
"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)