如需本資源的方法清單,請見本頁結尾。
資源表示法
DoubleClick Search 報表。這個物件包含報表要求、部分報表中繼資料 (例如貨幣代碼),以及產生的報表列或報表檔案。
{ "kind": "doubleclicksearch#report", "id": string, "isReportReady": boolean, "request": { "reportScope": { "agencyId": long, "advertiserId": long, "engineAccountId": long, "campaignId": long, "adGroupId": long, "keywordId": long, "adId": long }, "reportType": string, "columns": [ { "columnName": string, "savedColumnName": string, "customDimensionName": string, "customMetricName": string, "headerText": string, "startDate": string, "endDate": string, "groupByColumn": boolean, "platformSource": string, "productReportPerspective": string } ], "timeRange": { "startDate": string, "endDate": string, "changedMetricsSinceTimestamp": datetime, "changedAttributesSinceTimestamp": datetime }, "filters": [ { "column": { "columnName": string, "savedColumnName": string, "customDimensionName": string, "customMetricName": string, "headerText": string, "startDate": string, "endDate": string, "groupByColumn": boolean, "platformSource": string, "productReportPerspective": string }, "operator": string, "values": [ (value) ] } ], "orderBy": [ { "column": { "columnName": string, "savedColumnName": string, "customDimensionName": string, "customMetricName": string, "headerText": string, "startDate": string, "endDate": string, "groupByColumn": boolean, "platformSource": string, "productReportPerspective": string }, "sortOrder": string } ], "includeDeletedEntities": boolean, "includeRemovedEntities": boolean, "verifySingleTimeZone": boolean, "downloadFormat": string, "statisticsCurrency": string, "startRow": integer, "rowCount": integer, "maxRowsPerFile": integer }, "statisticsCurrencyCode": string, "statisticsTimeZone": string, "rowCount": integer, "files": [ { "url": string, "byteCount": long } ], "rows": [ { (key): (value) } ] }
資源名稱 | 值 | 說明 | Notes |
---|---|---|---|
files[] |
list |
僅限非同步報表。包含報表順利完成後產生的報表檔案清單。 | |
files[].byteCount |
long |
此報表檔案的大小 (以位元組為單位)。 | |
files[].url |
string |
請使用這個網址下載報告檔案。 | |
id |
string |
僅限非同步報表。報表的 ID。 | |
isReportReady |
boolean |
僅限非同步報表。只有在報告順利完成並可供下載報告檔案時,才會傳回 True。 | |
kind |
string |
標識為報表資源。值:固定字串 doubleclicksearch#report 。 |
|
request |
nested object |
建立報表的要求。原始要求中未指定的選填欄位會填入預設值。 | |
request.columns[] |
list |
要納入報表的資料欄。這包括 DoubleClick Search 資料欄和已儲存的資料欄。如果是 DoubleClick Search 資料欄,則只需要使用 columnName 參數。對於已儲存的資料欄,只需要 savedColumnName 參數。columnName 和 savedColumnName 不能在同一個 Stanza 中設定。每個要求的資料欄數量上限為 300 個。 |
|
request.columns[].columnName |
string |
要納入報表的 DoubleClick Search 欄名稱。 | |
request.columns[].customDimensionName |
string |
使用自訂維度區隔報表。報表的範圍僅限於廣告客戶或更低層級,且已在 DoubleClick Search 中設定自訂維度。DoubleClick Search 中的自訂維度名稱有大小寫之分。 如果在轉換報表中使用,系統會針對指定的轉換傳回指定自訂維度的值 (如有設定)。此資料欄不會區隔轉換報表。 |
|
request.columns[].customMetricName |
string |
要包含在報表中的自訂指標名稱。報表的範圍必須限定為廣告客戶或更低層級,而且自訂指標必須已在 DoubleClick Search 中設定。DoubleClick Search 中顯示的自訂指標名稱有大小寫之分。 | |
request.columns[].endDate |
string |
以 YYYY-MM-DD 格式輸入日期。提供這項資訊後,這只會覆寫這一欄的報表整體時間範圍。必須與 startDate 一併提供。 |
|
request.columns[].groupByColumn |
boolean |
僅限同步報告。設為「true 」即可依這一欄進行分組。預設為 false 。 |
|
request.columns[].headerText |
string |
用於在報表輸出中識別此欄的文字;如未指定,則預設為 columnName 或 savedColumnName 。這可以防止 DoubleClick Search 資料欄與名稱相同的已儲存資料欄發生衝突。 |
|
request.columns[].platformSource |
string |
這個維度可用來為自訂維度提供資料。可接受的值為「泛光燈」。 | |
request.columns[].productReportPerspective |
string |
只傳回特定產品類型活動的指標。接受的值如下:
|
|
request.columns[].savedColumnName |
string |
要納入報表的已儲存欄名稱。報表的範圍必須為廣告客戶或更低層級,而此已儲存的欄必須已在 DoubleClick Search 使用者介面中建立。 | |
request.columns[].startDate |
string |
包含日期,格式為 YYYY-MM-DD。提供這項資訊後,這只會覆寫這一欄的報表整體時間範圍。必須與 endDate 一併提供。 |
|
request.downloadFormat |
string |
報表要採用的格式。目前僅支援 csv 或 tsv 。 |
|
request.filters[] |
list |
要套用至報表的篩選器清單。 每個要求篩選器數量上限為 300 個。 |
|
request.filters[].column |
nested object |
要執行篩選器的資料欄。可以是 DoubleClick Search 資料欄或已儲存的資料欄。 | |
request.filters[].column.columnName |
string |
要納入報表的 DoubleClick Search 欄名稱。 | |
request.filters[].column.customDimensionName |
string |
使用自訂維度區隔報表。報表的範圍僅限於廣告客戶或更低層級,且已在 DoubleClick Search 中設定自訂維度。DoubleClick Search 中的自訂維度名稱有大小寫之分。 如果在轉換報表中使用,系統會針對指定的轉換傳回指定自訂維度的值 (如有設定)。此資料欄不會區隔轉換報表。 |
|
request.filters[].column.customMetricName |
string |
要包含在報表中的自訂指標名稱。報表的範圍必須限定為廣告客戶或更低層級,而且自訂指標必須已在 DoubleClick Search 中設定。DoubleClick Search 中顯示的自訂指標名稱有大小寫之分。 | |
request.filters[].column.endDate |
string |
以 YYYY-MM-DD 格式輸入日期。提供這項資訊後,這只會覆寫這一欄的報表整體時間範圍。必須與 startDate 一併提供。 |
|
request.filters[].column.groupByColumn |
boolean |
僅限同步報告。設為「true 」即可依這一欄進行分組。預設為 false 。 |
|
request.filters[].column.headerText |
string |
用於在報表輸出中識別此欄的文字;如未指定,則預設為 columnName 或 savedColumnName 。這可以防止 DoubleClick Search 資料欄與名稱相同的已儲存資料欄發生衝突。 |
|
request.filters[].column.platformSource |
string |
這個維度可用來為自訂維度提供資料。可接受的值為「泛光燈」。 | |
request.filters[].column.productReportPerspective |
string |
只傳回特定產品類型活動的指標。接受的值如下:
|
|
request.filters[].column.savedColumnName |
string |
要納入報表的已儲存欄名稱。報表的範圍必須為廣告客戶或更低層級,而此已儲存的欄必須已在 DoubleClick Search 使用者介面中建立。 | |
request.filters[].column.startDate |
string |
包含日期,格式為 YYYY-MM-DD。提供這項資訊後,這只會覆寫這一欄的報表整體時間範圍。必須與 endDate 一併提供。 |
|
request.filters[].operator |
string |
要用於篩選器的運算子。如需可用運算子的清單,請參閱篩選器參考資料。 | |
request.filters[].values[] |
list |
要用來篩選資料欄值的值清單。 每個要求的篩選器值數量上限為 300。 |
|
request.includeDeletedEntities |
boolean |
決定是否要將已移除的實體納入報表。預設為 false 。已不適用,請改用 includeRemovedEntities 。 |
|
request.includeRemovedEntities |
boolean |
決定是否要將已移除的實體納入報表。預設值為 false 。 |
|
request.maxRowsPerFile |
integer |
僅限非同步報表。每個報表檔案的列數上限。大型欄位會依據這個欄位分成多個檔案。可接受的值為 1000000 到 100000000 (含首尾)。 |
|
request.orderBy[] |
list |
僅限同步報告。欄和指示清單,用於定義要對報表列執行的排序。 每項要求的訂單數量上限為 300 個。 |
|
request.orderBy[].column |
nested object |
要執行排序依據的資料欄。這可以是 DoubleClick Search 定義的資料欄或已儲存的資料欄。 | |
request.orderBy[].column.columnName |
string |
要納入報表的 DoubleClick Search 欄名稱。 | |
request.orderBy[].column.customDimensionName |
string |
使用自訂維度區隔報表。報表的範圍僅限於廣告客戶或更低層級,且已在 DoubleClick Search 中設定自訂維度。DoubleClick Search 中的自訂維度名稱有大小寫之分。 如果在轉換報表中使用,系統會針對指定的轉換傳回指定自訂維度的值 (如有設定)。此資料欄不會區隔轉換報表。 |
|
request.orderBy[].column.customMetricName |
string |
要包含在報表中的自訂指標名稱。報表的範圍必須限定為廣告客戶或更低層級,而且自訂指標必須已在 DoubleClick Search 中設定。DoubleClick Search 中顯示的自訂指標名稱有大小寫之分。 | |
request.orderBy[].column.endDate |
string |
以 YYYY-MM-DD 格式輸入日期。提供這項資訊後,這只會覆寫這一欄的報表整體時間範圍。必須與 startDate 一併提供。 |
|
request.orderBy[].column.groupByColumn |
boolean |
僅限同步報告。設為「true 」即可依這一欄進行分組。預設為 false 。 |
|
request.orderBy[].column.headerText |
string |
用於在報表輸出中識別此欄的文字;如未指定,則預設為 columnName 或 savedColumnName 。這可以防止 DoubleClick Search 資料欄與名稱相同的已儲存資料欄發生衝突。 |
|
request.orderBy[].column.platformSource |
string |
這個維度可用來為自訂維度提供資料。可接受的值為「泛光燈」。 | |
request.orderBy[].column.productReportPerspective |
string |
只傳回特定產品類型活動的指標。接受的值如下:
|
|
request.orderBy[].column.savedColumnName |
string |
要納入報表的已儲存欄名稱。報表的範圍必須為廣告客戶或更低層級,而此已儲存的欄必須已在 DoubleClick Search 使用者介面中建立。 | |
request.orderBy[].column.startDate |
string |
包含日期,格式為 YYYY-MM-DD。提供這項資訊後,這只會覆寫這一欄的報表整體時間範圍。必須與 endDate 一併提供。 |
|
request.orderBy[].sortOrder |
string |
排序方向,可以是 ascending 或 descending 。 |
|
request.reportScope |
object |
reportScope 是一組 ID,用來決定報表中要傳回哪些實體。必須從代理商想要設定的最低範圍層級完整 ID 歷程。 | |
request.reportScope.adGroupId |
long |
DS 廣告群組編號。 | |
request.reportScope.adId |
long |
DS 廣告 ID。 | |
request.reportScope.advertiserId |
long |
DS 廣告客戶 ID。 | |
request.reportScope.agencyId |
long |
DS 代理商 ID。 | |
request.reportScope.campaignId |
long |
DS 廣告活動編號。 | |
request.reportScope.engineAccountId |
long |
DS 引擎帳戶 ID。 | |
request.reportScope.keywordId |
long |
DS 關鍵字編號。 | |
request.reportType |
string |
決定報表傳回的資料列類型。例如,如果您指定 reportType: keyword ,報表中的每個資料列都會包含關鍵字相關資料。請參閱報表類型參考資料,瞭解各類型可用的資料欄。 |
|
request.rowCount |
integer |
僅限同步報告。要傳回的資料列數量上限,系統會捨棄其他資料列。可接受的值為 0 到 10000 (含首尾)。預設值為 10000 。 |
|
request.startRow |
integer |
僅限同步報告。要傳回的第一個資料列的零索引。可接受的值為 0 到 50000 (含首尾)。預設值為 0 。 |
|
request.statisticsCurrency |
string |
指定退款金額;可能的值包括:usd 、agency (如果報表範圍限定為代理商或較低層級)、advertiser (報表範圍限定為 * 廣告客戶或更低層級) 或 account (如果報表範圍限定為引擎帳戶或較低層級的話)。 |
|
request.timeRange |
object |
如果報表要求指標,這個引數將會用來限制指標在特定時間範圍內。 | |
request.timeRange.changedAttributesSinceTimestamp |
datetime |
包含 RFC 格式的 UTC 時間戳記 (例如2013-07-16T10:16:23.555Z 。請參閱其他參考資料,瞭解已變更屬性報表的運作方式。 |
|
request.timeRange.changedMetricsSinceTimestamp |
datetime |
包含 RFC 格式的 UTC 時間戳記 (例如2013-07-16T10:16:23.555Z 。請參閱其他參考說明,瞭解變更指標報表的運作方式。 |
|
request.timeRange.endDate |
string |
包含日期,格式為 YYYY-MM-DD。 | |
request.timeRange.startDate |
string |
包含日期,格式為 YYYY-MM-DD。 | |
request.verifySingleTimeZone |
boolean |
如果設為 true ,則只有在所有請求統計資料都來自單一時區時,系統才會建立報表。預設為 false 。 |
|
rowCount |
integer |
報表產生的資料列數,不含標頭。 | |
rows[] |
list |
僅限同步報告。產生的報表列。 | |
rows[].(key) |
any value |
指出此資料列中顯示的資料欄。這表示此資料列中,在對應的資料列中,每個欄都有一個非空白儲存格。 | |
statisticsCurrencyCode |
string |
報表中產生的所有金額貨幣代碼,包括使用者設定的值 (例如關鍵字出價設定) 和指標 (例如費用和收益)。報表的貨幣代碼則取決於報表要求的 statisticsCurrency 欄位。 |
|
statisticsTimeZone |
string |
如果報表的所有統計資料都來自同一時區,就會這樣。否則系統會取消設定這個欄位。 |
方法
- 產生
- 可立即產生並傳回報表。
- 取得
- 意見調查要求狀態的意見調查。
- getFile
- 下載採用 UTF-8 編碼的報表檔案。
- getIdMappingFile
- 下載 CSV 檔案 (以 UTF-8 編碼),包含舊版 Search Ads 360 與新版 Search Ads 360 之間的 ID 對應。在提出要求的廣告客戶中,檔案包含舊版 Search Ads 360 和新版 Search Ads 360 中所有的子實體 (例如引擎帳戶、廣告活動、廣告群組等)。
- 要求
- 在報表系統中插入報表要求。