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，則 reportTasks.query 要求含有 offset=900 和 limit=500 時，最多會傳回 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)

說明維度欄。DimensionsHeader 數量和 DimensionsHeader 數量的按順序與列數相符。
metricHeaders[]

object (MetricHeader)

說明指標欄。MetricHeaders 的數量和 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，某些維度組合區塊會彙整到「(其他)」列。高基數報表可能會發生這種情況。

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

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

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

object (SchemaRestrictionResponse)

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

string

此報表使用的貨幣代碼。適合用於將貨幣指標 (例如 purchaseRevenue) 格式化，以便以視覺化方式呈現。如果要求中指定了 currencyCode，這個回應參數會回應要求參數；否則，這個回應參數會是屬性目前的 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」或「Asia/Tokyo」。
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。