صفحه بندی نتایج پرس و جو

به منظور مدیریت مجموعه نتایج حاوی تعداد زیادی ردیف، زبان پرس‌وجوی مرکز بازرگانان از صفحه‌بندی پشتیبانی می‌کند. دو پارامتر برای کنترل صفحه‌بندی در بدنه درخواست reports.search موجود است: page_size و page_token ، علاوه بر یک فیلد خروجی در بدنه پاسخ : next_page_token .

پارامتر page_size حداکثر تعداد ردیف‌هایی را که می‌توان در یک درخواست بازیابی کرد، مشخص می‌کند. اگر مشخص نشود، به طور خودکار روی حداکثر اندازه صفحه یعنی ۱۰۰۰ ردیف تنظیم می‌شود.

پارامتر page_token توکن صفحه‌ای را که باید برگردانده شود، مشخص می‌کند. اگر مشخص نشود، صفحه اول برگردانده می‌شود. برای بازیابی صفحه بعدی، مقداری که به عنوان next_page_token از فراخوانی قبلی reports.search دریافت شده است، باید به عنوان page_token ارائه شود. هنگامی که یک page_token ارائه می‌شود، تمام پارامترهای دیگر در فراخوانی باید با فراخوانی قبلی که page_token برگردانده است، مطابقت داشته باشند تا از رفتار غیرمنتظره جلوگیری شود.

مثال:

SELECT
  segments.offer_id,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr
FROM MerchantPerformanceView
WHERE segments.date BETWEEN '2021-12-01' AND '2021-12-31'

برای این پرس‌وجو، فرض کنید حساب شامل ۱۰۰۰۰۰ offer_ids است و page_size روی ۲۰۰ تنظیم شده است. سپس مجموعه نتایج شامل ۲۰۰ شیء ReportRow در اولین پاسخ، همراه با یک next_page_token خواهد بود.

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

در اینجا یک مثال از بدنه پاسخ (پنج نتیجه اول به علاوه next_page_token ) آورده شده است:

{
  "results": [
    {
      "segments": {
        "offerId": "12345"
      },
      "metrics": {
        "clicks": "0",
        "impressions": "59",
        "ctr": 0
      }
    },
    {
      "segments": {
        "offerId": "12346"
      },
      "metrics": {
        "clicks": "9625",
        "impressions": "276695",
        "ctr": 0.034785594246372356
      }
    },
    {
      "segments": {
        "offerId": "12347"
      },
      "metrics": {
        "clicks": "148",
        "impressions": "22045",
        "ctr": 0.0067135404853708325
      }
    },
    {
      "segments": {
        "offerId": "12348"
      },
      "metrics": {
        "clicks": "11",
        "impressions": "1100",
        "ctr": 0.01
      }
    },
    {
      "segments": {
        "offerId": "12349"
      },
      "metrics": {
        "clicks": "569",
        "impressions": "62977",
        "ctr": 0.0090350445400701838
      }
    },
    ...
  ],
  "nextPageToken": "CMgB"
}

نکته کلیدی: next_page_token در پاسخی که شامل آخرین دسته از ردیف‌ها است، پر نمی‌شود.