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 中同時存在的所有子實體 (例如引擎帳戶、廣告活動、廣告群組等)。
要求
在報表系統中插入報表要求。