reportData.query 方法提供同步方式來擷取報表資料。與產生檔案型報表 (CSV 或 Excel) 的標準 Reports 服務不同，這個方法會直接在回應中傳回結構化 JSON 資料。因此非常適合用於即時擷取和探索資料。Report
總覽
請詳閱本指南，熟悉如何使用這個端點查詢 Campaign Manager 360 報表資料。
準備要求
建構 ReportDataQueryRequest，指定維度、指標、日期範圍、篩選條件和排序條件。
REST
{
"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 最多會傳回 10 個結果。如果符合要求結果少於 10 個，API 可能會傳回少於 10 個結果。
如有其他結果，回應會包含 nextPageToken。如要擷取下一頁結果，請再次傳送相同要求，並將 pageToken 欄位設為這個符記。其他所有要求參數則維持不變。
傳送要求
將 HTTP POST 要求傳送至 reportdata/query 端點：
POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query
請確認要求已透過標準 OAuth 2.0 憑證和必要範圍完成驗證。詳情請參閱「授權要求」。
成功回應
如果查詢成功，系統會傳回 HTTP 200 OK 回應，其中包含含有 columnHeaders、rows 和 totalRow 的 JSON 酬載。
{
"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- 單一匯總資料列，代表所有相符指標的總和。無法加總的維度欄位和指標 (例如觸及指標，如
uniqueReachTotalReach) 在這個資料列中會顯示空白 ("")。 nextPageToken- 如果還有其他資料列，後續要求會使用這個符記擷取下一頁。
延遲和逾時
由於這是同步端點，查詢會立即執行，資料也會直接在回應中傳回 (最多為 maxResults 分頁限制)。查詢的執行時間上限為 60 秒。如果查詢超出這個限制，API 會終止作業並傳回 HTTP 503 Service
Unavailable 錯誤。
如果遇到這個錯誤，請嘗試縮小日期範圍、縮小篩選器範圍 (例如依特定廣告主或廣告活動篩選)，或減少要求的維度和指標數量。或者，您也可以使用 reports.run 執行 Report，以非同步方式產生可下載的報表檔案。
查詢限制和條件
reportdata.query 端點會強制執行多項限制，確保回覆內容可靠。如果要求違反這些限制，系統會拒絕要求並傳回 HTTP 400 Bad Request 回應。
日期範圍限制
- 如果是自訂日期範圍，
startDate必須在所要求報表資料類型的資料可用期間內。詳情請參閱「資料可用性」一節。
指標和維度限制
配額限制
向這個端點發出的要求會耗用下列配額：
- 使用者速率限制：每位使用者每分鐘 120 個要求 (2 QPS)
- 每項專案每日上限：每項專案每天 10,000 個要求
如果要求超出這些限制，就會失敗並出現 HTTP 429 Too Many Requests 錯誤。如果您逐頁瀏覽結果，則系統會將每項新頁面的要求 (使用 pageToken 參數) 視為個別查詢，並計入配額。