為查詢結果分頁

為了處理含有大量資料列的結果集,Merchant Center 查詢語言支援分頁功能。您可以使用兩個參數來控制 reports.search 要求主體中的分頁:page_sizepage_token,以及回應主體中的一個輸出欄位:next_page_token

page_size 參數會指定在單一要求中擷取的資料列數量上限。如果未指定,則會自動設為頁面大小上限 (1000 列)。

page_token 參數會指定要傳回網頁的符記。如果未指定,則會傳回第一頁。如要擷取後續頁面,應以 page_token 的形式提供前一個 reports.search 呼叫中以 next_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"
}