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)

說明維度欄。DimensionHeaders 的數量和排序，與資料列中的維度相符。
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,
  "samplingMetadatas": [
    {
      object (SamplingMetadata)
    }
  ],
  "schemaRestrictionResponse": {
    object (SchemaRestrictionResponse)
  },
  "currencyCode": string,
  "timeZone": string,
  "emptyReason": string,
  "subjectToThresholding": boolean
}
欄位
dataLossFromOtherRow

boolean

如果為 true，表示某些維度組合的值會歸入「(其他)」列。這可能會發生在高基數報表中。

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

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

如需更多資訊，請參閱「關於「(其他)」列和資料取樣」。
samplingMetadatas[]

object (SamplingMetadata)

如果這份報表結果是抽樣，這項資料會說明這份報表中所使用的事件百分比。每個日期範圍都會填入一個 samplingMetadatas。每個 samplingMetadatas 都會對應到要求中指定的日期範圍。

不過，如果結果未經過取樣，這個欄位就不會定義。
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

在特定 Google Analytics 資源中，您可能無法查看的資料類別。

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