داده‌های گزارش پرس‌وجو

متد reportData.query روشی همزمان برای بازیابی داده‌های گزارش ارائه می‌دهد. برخلاف سرویس استاندارد Reports که گزارش‌های مبتنی بر فایل (CSV یا Excel) تولید می‌کند، این متد داده‌های ساختاریافته JSON را مستقیماً در پاسخ برمی‌گرداند. این متد نیاز به تعریف، ایجاد و ذخیره یک منبع Report از قبل را از بین می‌برد و آن را برای بازیابی و کاوش داده‌های بلادرنگ ایده‌آل می‌کند.

نمای کلی

برای آشنایی با نحوه استفاده از این نقطه پایانی برای پرس و جو از داده‌های گزارش Campaign Manager 360 خود، این راهنما را مطالعه کنید.

درخواست را آماده کنید

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

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}

dateRange

یک شیء DateRange که دوره زمانی مورد نظر برای پرس و جو را مشخص می‌کند. این می‌تواند یک محدوده تاریخ سفارشی یا یک محدوده تاریخ نسبی باشد.

dimensionNames

فهرستی از نام‌های ابعاد استاندارد برای گروه‌بندی بر اساس آنها.

metricNames

الزامی. فهرستی از نام‌های استاندارد معیارها که باید لحاظ شوند.

dimensionFilters

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

sortBys

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

maxResults

حداکثر تعداد ردیف‌هایی که در هر صفحه برگردانده می‌شوند (پیش‌فرض: 100 ، حداکثر: 1000 ).

صفحه بندی

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

اگر نتایج بیشتری موجود باشد، پاسخ شامل یک nextPageToken می‌شود. برای بازیابی صفحه بعدی نتایج، همان درخواست را دوباره با فیلد pageToken که روی این توکن تنظیم شده است، ارسال کنید. سایر پارامترهای درخواست را یکسان نگه دارید.

درخواست را ارسال کنید

ارسال یک درخواست HTTP POST به نقطه پایانی reportdata/query :

POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query

اطمینان حاصل کنید که درخواست شما با اعتبارنامه‌های استاندارد OAuth 2.0 و حوزه‌های لازم تأیید شده است. برای اطلاعات بیشتر به بخش «درخواست‌های مجاز» مراجعه کنید.

پاسخ موفقیت‌آمیز

یک پرس‌وجوی موفق، یک پاسخ HTTP 200 OK با یک فایل JSON شامل columnHeaders ، rows و totalRow برمی‌گرداند.

{
  "columnHeaders": [
    { "name": "advertiser", "type": "DIMENSION" },
    { "name": "campaign", "type": "DIMENSION" },
    { "name": "impressions", "type": "METRIC" },
    { "name": "clicks", "type": "METRIC" }
  ],
  "rows": [
    {
      "values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
    },
    {
      "values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
    }
  ],
  "totalRow": {
    "values": [ "", "", "150831", "422" ]
  },
  "nextPageToken": "1234567890"
}

columnHeaders

نام و نوع ( DIMENSION یا METRIC ) فیلدهای برگردانده شده.

rows

فهرستی از اشیاء ReportDataRow که حاوی نتایج پرس و جو هستند. مقادیر رشته‌ای در هر ردیف بر اساس موقعیت با columnHeaders تراز می‌شوند.

totalRow

یک ردیف تجمیعی واحد که مجموع تمام معیارهای منطبق را نشان می‌دهد. فیلدهای ابعاد و معیارهایی که قابل جمع نیستند (برای مثال، معیارهای Reach مانند uniqueReachTotalReach ) در این ردیف خالی هستند ( "" )

nextPageToken

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

تأخیر و وقفه‌ها

از آنجا که این یک نقطه پایانی همزمان است، کوئری‌ها بلافاصله اجرا می‌شوند و داده‌ها مستقیماً در پاسخ بازگردانده می‌شوند (تا محدودیت صفحه‌بندی maxResults ). کوئری‌ها حداکثر زمان اجرای ۶۰ ثانیه دارند. اگر یک کوئری از این محدودیت فراتر رود، API عملیات را خاتمه می‌دهد و خطای HTTP 503 Service Unavailable را برمی‌گرداند.

اگر با این خطا مواجه شدید، سعی کنید محدوده تاریخ را محدودتر کنید، فیلترها را محدودتر کنید (مانند فیلتر کردن بر اساس تبلیغ‌کنندگان یا کمپین‌های خاص)، یا تعداد ابعاد و معیارهای درخواستی را کاهش دهید. روش دیگر، اجرای یک Report با استفاده از reports.run برای تولید یک فایل گزارش قابل دانلود به صورت غیرهمزمان است.

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

نقطه پایانی reportdata.query محدودیت‌های متعددی را برای اطمینان از پاسخ‌های قابل اعتماد اعمال می‌کند. درخواست‌هایی که این محدودیت‌ها را نقض می‌کنند با پاسخ HTTP 400 Bad Request رد می‌شوند.

محدودیت‌های محدوده تاریخ

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

محدودیت‌های متریک و ابعاد

• حداقل یک معیار باید در metricNames ارائه شود.
• معیارها و ابعاد موجود در لیست‌های metricNames و dimensionNames باید منحصر به فرد باشند.
• معیارها و ابعادی که به عنوان فقط دانلود برچسب گذاری شده‌اند، نمی‌توانند در این پرس‌وجوها استفاده شوند.

محدودیت‌های سهمیه

درخواست‌های ارسالی به این نقطه پایانی، سهمیه‌های زیر را مصرف می‌کنند:

• محدودیت سرعت کاربر: ۱۲۰ درخواست در دقیقه برای هر کاربر (۲ QPS)
• محدودیت روزانه برای هر پروژه: ۱۰،۰۰۰ درخواست در روز برای هر پروژه

درخواست‌هایی که از این محدودیت‌ها تجاوز کنند، با خطای HTTP 429 Too Many Requests مواجه می‌شوند. اگر نتایج را صفحه به صفحه بررسی کنید، هر درخواست برای یک صفحه جدید (با استفاده از پارامتر pageToken ) به عنوان یک کوئری جداگانه حساب می‌شود و از این سهمیه استفاده می‌کند.