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

產生並傳回報表。立即試用。

要求

HTTP 要求

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

授權

此要求需要以下範圍的授權：

範圍
`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 廣告活動編號。
`reportScope.adGroupId`	`long`	DS 廣告群組編號。
`reportScope.keywordId`	`long`	DS 關鍵字編號。
`reportScope.adId`	`long`	DS 廣告 ID。
`reportType`	`string`	決定報表傳回的資料列類型。例如，如果您指定 `reportType: keyword`，報表中的每個資料列都會包含關鍵字相關資料。請參閱報表類型參考資料，瞭解各類型可用的資料欄。
`columns[]`	`list`	要納入報表的資料欄。這包括 DoubleClick Search 資料欄和已儲存的資料欄。如果是 DoubleClick Search 資料欄，則只需要使用 `columnName` 參數。對於已儲存的資料欄，只需要 `savedColumnName` 參數。`columnName` 和 `savedColumnName` 不能在同一個 Stanza 中設定。每個要求的資料欄數量上限為 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`	這個維度可用來為自訂維度提供資料。可接受的值為「泛光燈」。
`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`	這個維度可用來為自訂維度提供資料。可接受的值為「泛光燈」。
`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`	這個維度可用來為自訂維度提供資料。可接受的值為「泛光燈」。
`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。