舊版 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` 不能在同一個 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`	只傳回特定產品類型活動的指標。接受的值如下：「`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`	這個維度可用來為自訂維度提供資料。可接受的值為「泛光燈」。
`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`	這個維度可用來為自訂維度提供資料。可接受的值為「泛光燈」。
`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 廣告群組編號。
`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 中所有的子實體 (例如引擎帳戶、廣告活動、廣告群組等)。
要求: 在報表系統中插入報表要求。