Method: properties.reportTasks.query

擷取報表工作的內容。要求 reportTasks.create 後，您可以在報表啟用後擷取報表內容。如果報表工作的狀態不是 ACTIVE，這個方法就會傳回錯誤。查詢回應會傳回表格列，資料欄中的值。

HTTP 要求

POST https://analyticsdata.googleapis.com/v1alpha/{name=properties/*/reportTasks/*}:query

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
name

string

必要欄位。報表來源名稱。格式：properties/{property}/reportTasks/{report}

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "offset": string,
  "limit": string
}
欄位
offset

string (int64 format)

選用設定。報表中起始列的列數。第一列會計為第 0 列。

分頁時，第一個要求不會指定位移；或等於，將偏移值設為 0；第一個要求會傳回前 limit 列。第二個要求將偏移值設為第一個要求的 limit；第二個要求會傳回第二列的 limit 列。

如要進一步瞭解這個分頁參數，請參閱「分頁」。
limit

string (int64 format)

選用設定。報表中要傳回的列數。如未指定，系統會傳回 10,000 列。無論您要求多少列，API 在每個要求最多只能傳回 250,000 列。limit必須為正數。

如果維度值數量不如 limit，API 也可以傳回少於要求的 limit 列。QueryReportTaskRequest 可用的列數會進一步限定為相關 ReportTask 的上限。查詢最多只能擷取 ReportTask.limit 列。舉例來說，如果 ReportTask 的限制為 1,000，則使用 offset=900 和 limit=500 的 reportTasks.query 要求，最多會傳回 100 列。

如要進一步瞭解這個分頁參數，請參閱「分頁」。

回應主體

與報表工作對應的報表內容。

如果成功，回應主體會含有以下結構的資料：

JSON 表示法 
{
  "dimensionHeaders": [
    {
      object (DimensionHeader)
    }
  ],
  "metricHeaders": [
    {
      object (MetricHeader)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totals": [
    {
      object (Row)
    }
  ],
  "maximums": [
    {
      object (Row)
    }
  ],
  "minimums": [
    {
      object (Row)
    }
  ],
  "rowCount": integer,
  "metadata": {
    object (ResponseMetaData)
  }
}
欄位
dimensionHeaders[]

object (DimensionHeader)

說明維度欄。DimensionsHeaders 的數量和順序與資料列中的維度相符。
metricHeaders[]

object (MetricHeader)

說明指標欄。MetricHeaders 的數量和排序與資料列中顯示的指標相符。
rows[]

object (Row)

報表中的維度值組合和指標值。
totals[]

object (Row)

如有要求，則指標總值。
maximums[]

object (Row)

如有要求，則指標的最大值。
minimums[]

object (Row)

視需要提供指標的最小值。
rowCount

integer

查詢結果中的資料列總數。
metadata

object (ResponseMetaData)

報表的中繼資料。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/analytics

ResponseMetaData

回應的中繼資料，內含報表內容的其他資訊。

JSON 表示法 
{
  "dataLossFromOtherRow": boolean,
  "schemaRestrictionResponse": {
    object (SchemaRestrictionResponse)
  },
  "currencyCode": string,
  "timeZone": string,
  "emptyReason": string,
  "subjectToThresholding": boolean
}
欄位
dataLossFromOtherRow

boolean

若為 true，代表某些維度組合區間會彙整至「(other)」項目列。高基數報表可能就會發生這種情況。

中繼資料參數 dataLossFromOtherRow 會根據報表中使用的匯總資料表填入。無論報表中的篩選器和限制為何，系統都會準確填入這個參數。

舉例來說，由於請求含有 sessionSource = google 的篩選器，因此報表可能遭到捨棄「(other)」列。如果用來產生這份報表的輸入匯總資料中，有其他資料列的資料遺失，系統仍會填入這個參數。

詳情請參閱關於「(other)」列和資料取樣。
schemaRestrictionResponse

object (SchemaRestrictionResponse)

說明建立這份報表時主動執行的結構定義限制。詳情請參閱「存取權和資料限制管理」。
currencyCode

string

這份報表中使用的貨幣代碼。適用於為 purchaseRevenue 等貨幣指標設定格式，以便呈現視覺化結果。如果請求中已指定貨幣代碼，則此回應參數會回應請求參數。否則，這個回應參數就是屬性目前的 currencyCode。

貨幣代碼是 ISO 4217 標準貨幣類型的字串編碼 (https://en.wikipedia.org/wiki/ISO_4217)；例如「USD」、「EUR」、「JPY」。詳情請參閱：https://support.google.com/analytics/answer/9796179。
timeZone

string

資源目前的時區。適用於解讀以時間為準的維度，例如 hour 和 minute。採用 IANA 時區資料庫 (https://www.iana.org/time-zones) 的字串；例如「America/New_York」或「亞洲/東京」
emptyReason

string

如果指定空白原因，這個原因會導致報表空白。
subjectToThresholding

boolean

如果 subjectToThresholding 為 true，這份報表就會發生閾值，且只會傳回達到最低匯總閾值的資料。某要求可能設有閾值，因此報表中沒有任何資料，只要所有資料超過閾值，就有可能發生這種情況。詳情請參閱「資料門檻」和「關於客層和興趣」這兩篇文章。

SchemaRestrictionResponse

建立這份報表時主動強制執行的結構定義限制。詳情請參閱「存取權和資料限制管理」。

JSON 表示法 
{
  "activeMetricRestrictions": [
    {
      object (ActiveMetricRestriction)
    }
  ]
}
欄位
activeMetricRestrictions[]

object (ActiveMetricRestriction)

我們在建立報表時積極強制執行的所有限制。舉例來說，purchaseRevenue 一律採用 REVENUE_DATA 限制類型。不過，只有在使用者的自訂角色不允許存取 REVENUE_DATA 時，系統才會填入這項有效回應限制。

ActiveMetricRestriction

用來建立報表的指標。

JSON 表示法 
{
  "restrictedMetricTypes": [
    enum (RestrictedMetricType)
  ],
  "metricName": string
}
欄位
restrictedMetricTypes[]

enum (RestrictedMetricType)

這項指標限制的原因。
metricName

string

受限制指標的名稱。

RestrictedMetricType

您可能會禁止在某些 GA4 資源中查看的資料類別。

列舉
RESTRICTED_METRIC_TYPE_UNSPECIFIED 未指定類型。
COST_DATA 費用指標，例如 adCost。
REVENUE_DATA 收益指標，例如 purchaseRevenue。