تقسيم نتائج طلب البحث على صفحات

من أجل التعامل مع مجموعات النتائج التي تحتوي على عدد كبير من الصفوف، تتيح "لغة طلبات البحث في Merchant Center" تقسيم النتائج إلى صفحات. تتوفّر مَعلمتَان للتحكّم في تقسيم النتائج إلى صفحات في نص طلب reports.search، وهما page_size وpage_token، بالإضافة إلى حقل إخراج واحد في نص الاستجابة، وهو next_page_token.

تحدّد المَعلمة page_size الحد الأقصى لعدد الصفوف التي سيتم استردادها في طلب واحد. في حال عدم تحديدها، يتم ضبطها تلقائيًا على الحد الأقصى لحجم الصفحة البالغ 1000 صف.

تحدّد المَعلمة 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'

بالنسبة إلى طلب البحث هذا، افترِض أنّ الحساب يتضمّن 100,000 offer_ids وأنّ قيمة page_size هي 200. ستحتوي مجموعة النتائج بعد ذلك على 200 عنصر ReportRow في الاستجابة الأولى، بالإضافة إلى next_page_token.

لاسترداد الـ 200 صف التالية، أرسِل الطلب مرة أخرى مع حجم الصفحة نفسه، ولكن عدِّل 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"
}