舊版 Search Ads 360 Reporting API 即將淘汰，於 2024 年 6 月 30 日停用。請注意，Search Ads 360 Conversion API 不會受到影響，並會繼續支援。所有新的報表開發作業都應使用新版 Search Ads 360 Reporting API。

自 2024 年 4 月起，您要求報表時將傳回 supportedApiVersion 錯誤。相關詳情請參閱這篇說明文章。

我們也強烈建議您將所有現有的 Search Ads 360 導入作業遷移至新版 API。詳情請參閱新版 Search Ads 360 Reporting API 入門指南和遷移指南。

本頁面由 Cloud Translation API 翻譯而成。

Reports

如需本資源的方法清單，請見本頁結尾。

資源表示法

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)
    }
  ]
}

屬性名稱	值	說明
`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` 不得於同一個條目中設定。每項要求最多只能有 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`	用來提供自訂維度資料的平台。可接受的值為「Floodlight」。
`request.columns[].productReportPerspective`	`string`	只傳回特定類型的產品活動的指標。可接受的值如下：「`sold`」：僅傳回售出產品的指標「`advertised`」：只會傳回購物廣告活動中宣傳且可能尚未售出的產品相關指標
`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`	用來提供自訂維度資料的平台。可接受的值為「Floodlight」。
`request.filters[].column.productReportPerspective`	`string`	只傳回特定類型的產品活動的指標。可接受的值如下：「`sold`」：僅傳回售出產品的指標「`advertised`」：只會傳回購物廣告活動中宣傳且可能尚未售出的產品相關指標
`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`	用來提供自訂維度資料的平台。可接受的值為「Floodlight」。
`request.orderBy[].column.productReportPerspective`	`string`	只傳回特定類型的產品活動的指標。可接受的值如下：「`sold`」：僅傳回售出產品的指標「`advertised`」：只會傳回購物廣告活動中宣傳且可能尚未售出的產品相關指標
`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 廣告群組 ID。
`request.reportScope.adId`	`long`	DS 廣告 ID。
`request.reportScope.advertiserId`	`long`	DS 廣告主 ID。
`request.reportScope.agencyId`	`long`	DS 代理商 ID。
`request.reportScope.campaignId`	`long`	DS 廣告活動 ID。
`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: 下載採用 UTF-8 編碼的 CSV 檔案，其中包含舊版 Search Ads 360 與新版 Search Ads 360 之間的 ID 對應。對於要求的廣告客戶，檔案會納入舊版和新版 Search Ads 360 中同時存在的所有子實體 (例如引擎帳戶、廣告活動、廣告群組等)。
要求: 在報表系統中插入報表要求。