راهنمای توسعه دهنده

این سند نحوه استفاده از Real Time Reporting API را برای دریافت داده های Google Analytics توضیح می دهد.

معرفی

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

اگر با API تازه کار هستید، برای آشنایی با API گزارش زمان واقعی و داده هایی که ارائه می دهد، نمای کلی API Reporting Time را بخوانید.

پيش نياز

قبل از استفاده از Real Time Reporting API برای دریافت داده های Google Analytics:

  • صفحه کتابخانه های سرویس گیرنده را برای لیست کاملی از کتابخانه های مشتری خاص زبان برنامه نویسی که با API کار می کنند، بخوانید.
  • راهنمای مرجع را بخوانید تا یاد بگیرید چگونه از API به تنهایی (بدون استفاده از کتابخانه مشتری) برای دریافت داده های Google Analytics استفاده کنید.

هر کتابخانه مشتری یک شی سرویس تجزیه و تحلیل واحد را برای دسترسی به تمام داده های API گزارش زمان واقعی ارائه می دهد. برای ایجاد یک شیء سرویس:

  1. برنامه خود را در Google API Console ثبت کنید.
  2. اجازه دسترسی به داده های Google Analytics را بدهید.
  3. یک شیء سرویس Analytics ایجاد کنید.

اگر این مراحل را کامل نکرده‌اید، لطفاً دست از کار بکشید و آموزش Hello Google Analytics API را بخوانید، که شما را در مراحل اولیه ساخت یک برنامه API Google Analytics راهنمایی می‌کند. پس از آن می دانید چگونه از API برای دریافت داده های Google Analytics استفاده کنید.

با استفاده از Real Time Reporting API

برای استفاده از Real Time Reporting API، یک برنامه:

  1. API گزارش زمان واقعی را پرس و جو می کند.
  2. پاسخ API را مدیریت می کند.

پرس و جو از API گزارش زمان واقعی

شیء سرویس تجزیه و تحلیل روشی را برای ایجاد یک جستار API گزارش زمان واقعی ارائه می دهد. برای جزئیات بیشتر در مورد پارامترهای پرس و جو و داده های موجود در API، بخوانید:

پس از اینکه یک پرس و جو را تعریف کردید، روش execute آن را فراخوانی کنید تا پرس و جو به سرورهای Google Analytics ارسال شود.

مدیریت پاسخ API

اگر یک پرس و جو به API گزارش زمان واقعی موفقیت آمیز باشد، API داده های درخواستی را به عنوان بخشی از یک منبع داده بلادرنگ برمی گرداند. برای جزئیات بیشتر در مورد ساختار و فرمت پاسخ API به مرجع Real Time Reporting API مراجعه کنید.

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

نمونه های کد

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

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

اینها محدودیت‌هایی هستند که در پرس و جوهای Real Time API وجود دارد:

  • اگر متریک rt:activeUsers در پرس و جوی با فیلترهای ابعاد زیر گنجانده شود، تنها عملگر AND و نوع تطابق برابری ( == ) پشتیبانی می شود.
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    از آنجایی که معیار rt:activeUsers فقط تعداد کاربران فعال در سایت را در حال حاضر بازیابی می کند، rt:minutesAgo با rt:activeUsers استفاده نکنید. یعنی rt:activeUsers به ​​این معنی است که rt:minutesAgo 0 است.

  • هیچ پشتیبانی از فیلترهای متریک وجود ندارد.
  • هیچ پشتیبانی از پارامتر fields وجود ندارد.

مدیریت سهمیه

همانطور که در Limits and Quota توضیح داده شد، سهمیه‌های روزانه برای API گزارش زمان واقعی وجود دارد که با سایر APIهای Google Analytics به اشتراک گذاشته می‌شود. اگر در فواصل زمانی کوتاهی از API گزارش زمان واقعی نظرسنجی می‌کنید، خیلی سریع به محدودیت‌های سهمیه روزانه می‌رسید. وقتی این اتفاق می‌افتد، درخواست‌های دیگر APIهای Google Analytics نیز تا زمانی که سهمیه به‌روزرسانی نشود، کار نمی‌کنند.

برخی از نمونه‌های پیاده‌سازی که ممکن است خیلی سریع از سهمیه استفاده کنند عبارتند از :

  • شما چندین داشبورد بیدرنگ دارید که به صورت روزانه در فواصل زمانی بسیار کوتاه، داده ها را برای یک نمای گوگل آنالیتیکس (نمایه) جستجو می کنند.
  • شما دارای یک دارایی با کاربران زیادی هستید و یک ویجت زمان واقعی را پیاده سازی کرده اید. هر بار که ویجت به یک کاربر نمایش داده می شود، به جای استفاده از کش، مستقیماً از Google Analytics سؤال می کنید.

برای به حداقل رساندن استفاده از سهمیه و مدیریت موثر آن:

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

مثال: محاسبه فاصله بازخوانی

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

به عنوان مثال، یک نمای گوگل آنالیتیکس (نمایه) دارای محدودیت سهمیه روزانه 10000 درخواست در روز است. اگر انتظار دارید در یک روز 6000 پرس و جو به Core Reporting API برای یک نما (نمایه) انجام دهید، در این صورت یک سهمیه 4000 درخواست برای آن نما (نمایه) باقی می ماند.

فرض کنید تصمیم دارید از Real Time Reporting API برای پیاده سازی 3 داشبورد بلادرنگ استفاده کنید که تمام روز را برای داده های بلادرنگ از یک نمای (نمایه) جستجو می کنند. هر داشبورد می تواند تقریباً 1333 پرس و جو در روز (4000 پرس و جو / 3 داشبورد) ایجاد کند. 86400 ثانیه در روز وجود دارد. بنابراین فاصله بازخوانی برای هر داشبورد باید بیشتر از 65 ثانیه (86,400 / 1,333) باشد تا تعداد کل درخواست‌های روزانه برای مشاهده (نمایه) کمتر از حد مجاز روزانه 4000 باشد.