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

資源目前的時區。適用於解讀以時間為準的維度,例如 hourminute。採用 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