舊版 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: request

將報表要求插入報表系統。立即試用。

要求

HTTP 要求

POST https://www.googleapis.com/doubleclicksearch/v2/reports

授權

此要求需要具有下列範圍的授權：

範圍
`https://www.googleapis.com/auth/doubleclicksearch`

詳情請參閱「驗證與授權」網頁。

要求主體

在要求主體中，提供具有以下結構的資料：

{
  "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
}

屬性名稱	值	說明
`reportScope`	`object`	reportScope 是一組 ID，用來決定報表中要傳回哪些實體。必須透過代理商指定的最低範圍層級 ID 完整歷程。
`reportScope.agencyId`	`long`	DS 代理商 ID。
`reportScope.advertiserId`	`long`	DS 廣告主 ID。
`reportScope.engineAccountId`	`long`	DS 引擎帳戶 ID。
`reportScope.campaignId`	`long`	DS 廣告活動 ID。
`reportScope.adGroupId`	`long`	DS 廣告群組 ID。
`reportScope.keywordId`	`long`	DS 關鍵字編號。
`reportScope.adId`	`long`	DS 廣告 ID。
`reportType`	`string`	決定報表中傳回的列類型。舉例來說，如果您指定 `reportType: keyword`，報表中的每個資料列都會包含關鍵字的相關資料。如要瞭解各類型可用的資料欄，請參閱報表類型參考資料。
`columns[]`	`list`	要納入報表的資料欄。這些資料包括 DoubleClick Search 資料欄和已儲存的資料欄。針對 DoubleClick Search 資料欄，您只需要 `columnName` 參數。已儲存的資料欄只需要 `savedColumnName` 參數。`columnName` 和 `savedColumnName` 不得於同一個條目中設定。每項要求最多只能有 300 個資料欄。
`columns[].columnName`	`string`	要納入報表的 DoubleClick Search 資料欄名稱。
`columns[].savedColumnName`	`string`	要納入報表的已儲存欄名稱。報表必須限定為廣告客戶或較低層級，且這個已儲存的資料欄必須事先在 DoubleClick Search 使用者介面中建立。
`columns[].headerText`	`string`	在報表輸出結果中用來識別此欄的文字。如未指定，會預設為 `columnName` 或 `savedColumnName`。這可用於防止 DoubleClick Search 資料欄與名稱相同的已儲存資料欄之間發生衝突。
`columns[].startDate`	`string`	截止日期，格式為 YYYY-MM-DD。如有提供，這個值只會覆寫此欄的報表總時間範圍資料。必須與 `endDate` 一併提供。
`columns[].endDate`	`string`	包含日期，格式為 YYYY-MM-DD。如有提供，這個值只會覆寫此欄的報表總時間範圍資料。必須與 `startDate` 一併提供。
`columns[].groupByColumn`	`boolean`	僅限同步報表。設為 `true` 即可按這一欄分組。預設為 `false`。
`timeRange`	`object`	如果在報表中請求指標，這個引數將用於將指標限制為特定時間範圍。
`timeRange.startDate`	`string`	截止日期，格式為 YYYY-MM-DD。
`timeRange.endDate`	`string`	截止日期，格式為 YYYY-MM-DD。
`timeRange.changedMetricsSinceTimestamp`	`datetime`	包含 RFC 格式且包含的 UTC 時間戳記，例如`2013-07-16T10:16:23.555Z`。如要瞭解已變更指標報表的運作方式，請參閱其他參考資料。
`timeRange.changedAttributesSinceTimestamp`	`datetime`	包含 RFC 格式且包含的 UTC 時間戳記，例如`2013-07-16T10:16:23.555Z`。如要瞭解屬性變更報表的運作方式，請參閱其他參考資料。
`filters[]`	`list`	一組要套用至報表的篩選器。每項要求的篩選器數量上限為 300 個。
`filters[].column`	`nested object`	要執行篩選器的資料欄。可以是 DoubleClick Search 資料欄或已儲存的資料欄。
`filters[].column.columnName`	`string`	要納入報表的 DoubleClick Search 資料欄名稱。
`filters[].column.savedColumnName`	`string`	要納入報表的已儲存欄名稱。報表必須限定為廣告客戶或較低層級，且這個已儲存的資料欄必須事先在 DoubleClick Search 使用者介面中建立。
`filters[].operator`	`string`	要在篩選器中使用的運算子。如需可用運算子的清單，請參閱篩選器參考資料。
`filters[].values[]`	`list`	用於篩選資料欄值的值清單。每項要求的篩選器值數量上限為 300 個。
`orderBy[]`	`list`	僅限同步報表。欄和方向清單，用於定義要對報表列執行的排序。每項要求的排序數量上限為 300 個。
`orderBy[].column`	`nested object`	要執行排序作業的資料欄。這可以是 DoubleClick Search 定義的資料欄或已儲存的資料欄。
`orderBy[].column.columnName`	`string`	要納入報表的 DoubleClick Search 資料欄名稱。
`orderBy[].column.savedColumnName`	`string`	要納入報表的已儲存欄名稱。報表必須限定為廣告客戶或較低層級，且這個已儲存的資料欄必須事先在 DoubleClick Search 使用者介面中建立。
`orderBy[].sortOrder`	`string`	排序方向，即 `ascending` 或 `descending`。
`includeDeletedEntities`	`boolean`	決定是否要將已移除的實體加入報表。預設為 `false`。已淘汰，請改用 `includeRemovedEntities`。
`verifySingleTimeZone`	`boolean`	如果是 `true`，則只有在所有請求的統計資料都來自單一時區時，系統才會建立報表。預設為 `false`。
`downloadFormat`	`string`	應傳回報表的格式。目前支援 `csv` 或 `tsv`。
`statisticsCurrency`	`string`	指定傳回金額的貨幣。可能的值包括：`usd`、`agency` (如果報表範圍限定為代理商或更低層級，則為有效)、`advertiser` (如果報表範圍限定為 * 或更低層級，才有效) 或 `account` (如果報表範圍限定為引擎帳戶或更低層級，則有效)。
`startRow`	`integer`	僅限同步報表。要傳回的第一個資料列索引從零開始。可接受的值為 `0` 到 `50000` (含頭尾)。預設值為 `0`。
`rowCount`	`integer`	僅限同步報表。要傳回的資料列數量上限；捨棄更多資料列。可接受的值為 `0` 到 `10000` (含頭尾)。預設值為 `10000`。
`maxRowsPerFile`	`integer`	僅限非同步報表。每個報表檔案的列數上限。系統會根據這個欄位將大型報表分割為多個檔案。可接受的值為 `1000000` 到 `100000000` (含頭尾)。
`includeRemovedEntities`	`boolean`	決定是否要將已移除的實體加入報表。預設值為 `false`。
`columns[].customDimensionName`	`string`	依自訂維度區隔報表。報表必須將範圍限定在廣告客戶或更低層級，且該自訂維度必須已在 DoubleClick Search 中設定。DoubleClick Search 中的自訂維度名稱會區分大小寫。如果用於轉換報表，系統會傳回特定轉換的指定自訂維度值 (如有設定)。此欄不會區隔轉換報表。
`columns[].platformSource`	`string`	用來提供自訂維度資料的平台。可接受的值為「Floodlight」。
`filters[].column.customDimensionName`	`string`	依自訂維度區隔報表。報表必須將範圍限定在廣告客戶或更低層級，且該自訂維度必須已在 DoubleClick Search 中設定。DoubleClick Search 中的自訂維度名稱會區分大小寫。如果用於轉換報表，系統會傳回特定轉換的指定自訂維度值 (如有設定)。此欄不會區隔轉換報表。
`filters[].column.headerText`	`string`	在報表輸出結果中用來識別此欄的文字。如未指定，會預設為 `columnName` 或 `savedColumnName`。這可用於防止 DoubleClick Search 資料欄與名稱相同的已儲存資料欄之間發生衝突。
`filters[].column.startDate`	`string`	截止日期，格式為 YYYY-MM-DD。如有提供，這個值只會覆寫此欄的報表總時間範圍資料。必須與 `endDate` 一併提供。
`filters[].column.endDate`	`string`	包含日期，格式為 YYYY-MM-DD。如有提供，這個值只會覆寫此欄的報表總時間範圍資料。必須與 `startDate` 一併提供。
`filters[].column.groupByColumn`	`boolean`	僅限同步報表。設為 `true` 即可按這一欄分組。預設為 `false`。
`filters[].column.platformSource`	`string`	用來提供自訂維度資料的平台。可接受的值為「Floodlight」。
`orderBy[].column.customDimensionName`	`string`	依自訂維度區隔報表。報表必須將範圍限定在廣告客戶或更低層級，且該自訂維度必須已在 DoubleClick Search 中設定。DoubleClick Search 中的自訂維度名稱會區分大小寫。如果用於轉換報表，系統會傳回特定轉換的指定自訂維度值 (如有設定)。此欄不會區隔轉換報表。
`orderBy[].column.headerText`	`string`	在報表輸出結果中用來識別此欄的文字。如未指定，會預設為 `columnName` 或 `savedColumnName`。這可用於防止 DoubleClick Search 資料欄與名稱相同的已儲存資料欄之間發生衝突。
`orderBy[].column.startDate`	`string`	截止日期，格式為 YYYY-MM-DD。如有提供，這個值只會覆寫此欄的報表總時間範圍資料。必須與 `endDate` 一併提供。
`orderBy[].column.endDate`	`string`	包含日期，格式為 YYYY-MM-DD。如有提供，這個值只會覆寫此欄的報表總時間範圍資料。必須與 `startDate` 一併提供。
`orderBy[].column.groupByColumn`	`boolean`	僅限同步報表。設為 `true` 即可按這一欄分組。預設為 `false`。
`orderBy[].column.platformSource`	`string`	用來提供自訂維度資料的平台。可接受的值為「Floodlight」。
`columns[].customMetricName`	`string`	要納入報表的自訂指標名稱。報表必須將範圍限定在廣告客戶或較低層級，且該自訂指標必須已在 DoubleClick Search 中設定。DoubleClick Search 中的自訂指標名稱會區分大小寫。
`filters[].column.customMetricName`	`string`	要納入報表的自訂指標名稱。報表必須將範圍限定在廣告客戶或較低層級，且該自訂指標必須已在 DoubleClick Search 中設定。DoubleClick Search 中的自訂指標名稱會區分大小寫。
`orderBy[].column.customMetricName`	`string`	要納入報表的自訂指標名稱。報表必須將範圍限定在廣告客戶或較低層級，且該自訂指標必須已在 DoubleClick Search 中設定。DoubleClick Search 中的自訂指標名稱會區分大小寫。
`columns[].productReportPerspective`	`string`	只傳回特定類型的產品活動的指標。可接受的值如下：「`sold`」：僅傳回售出產品的指標「`advertised`」：只會傳回購物廣告活動中宣傳且可能尚未售出的產品相關指標
`filters[].column.productReportPerspective`	`string`	只傳回特定類型的產品活動的指標。可接受的值如下：「`sold`」：僅傳回售出產品的指標「`advertised`」：只會傳回購物廣告活動中宣傳且可能尚未售出的產品相關指標
`orderBy[].column.productReportPerspective`	`string`	只傳回特定類型的產品活動的指標。可接受的值如下：「`sold`」：僅傳回售出產品的指標「`advertised`」：只會傳回購物廣告活動中宣傳且可能尚未售出的產品相關指標

回應

如果成功，這個方法會在回應主體中傳回報表資源。

試試看！

使用下方的 APIs Explorer，針對即時資料呼叫這個方法，看看會有什麼結果。您也可以改用獨立式 Explorer。