本文件提供 Core Reporting API 3.0 版查詢和回應的完整參考資料。
簡介
您將透過 Core Reporting API 查詢 Google Analytics (分析) 報表資料。每項查詢都需要有資料檢視 (設定檔) ID、開始和結束日期,以及至少一項指標。您也可以提供其他查詢參數,例如維度、篩選器和區隔,藉此縮小查詢範圍。請參閱 總覽指南,瞭解這些概念如何搭配運作。
要求
API 提供單一要求資料的方法:
analytics.data.ga.get()
此方法會在不同的用戶端程式庫中公開,且具備語言專屬介面,可用來設定查詢參數。
此 API 也可做為符合 REST 樣式的端點進行查詢:
Authorization: Bearer {oauth2-token} GET https://www.googleapis.com/analytics/v3/data/ga ?ids=ga:12345 &start-date=2008-10-01 &end-date=2008-10-31 &metrics=ga:sessions,ga:bounces
每個網址查詢參數都指定一個必須進行網址編碼的 API 查詢參數。
查詢參數摘要
下表摘要列出 Core Reporting API 接受的所有查詢參數。按一下各參數名稱即可查看詳細說明。
名稱 | 值 | 必要 | 摘要 |
---|---|---|---|
ids |
string |
是 | 表單「ga:XXXX」的專屬資料表 ID,其中 XXXX 是查詢擷取資料的 Analytics (分析) 資料檢視 (設定檔) ID。 |
start-date |
string |
是 |
擷取 Analytics (分析) 資料的開始日期。要求可以指定採用 YYYY-MM-DD 格式的開始日期,或以相對日期的形式指定 (例如today 、yesterday 或 NdaysAgo ,其中 N 為正整數)。 |
end-date |
string |
是 |
擷取 Analytics (分析) 資料的結束日期。要求可以指定採用 YYYY-MM-DD 格式的結束日期或相對日期 (例如today 、yesterday 或 NdaysAgo ,其中 N 為正整數)。 |
metrics |
string |
是 |
以半形逗號分隔的指標清單,例如 ga:sessions,ga:bounces 。 |
dimensions |
string |
否 |
Analytics (分析) 資料維度清單 (以半形逗號分隔),例如 ga:browser,ga:city 。 |
sort |
string |
否 | 以半形逗號分隔的維度和指標清單,指出傳回資料的排序順序和排序方向。 |
filters |
string |
否 | 維度或指標篩選器,用於限制要求傳回的資料。 |
segment |
string |
否 | 區隔要求傳回的資料。 |
samplingLevel |
string |
否 | 所需的取樣層級。允許的值:
|
include-empty-rows |
boolean |
否 | 預設值為 true;如果設為 False,回應會略過所有指標值為零的資料列。 |
start-index |
integer |
否 |
要擷取的第一列資料,從 1 開始。請用這個參數做為分頁機制和 max-results 參數。 |
max-results |
integer |
否 | 要納入回應的資料列數量上限。 |
output |
string |
否 |
回應中傳回的 Analytics (分析) 資料所需的輸出類型。
可接受的值為 json 和 dataTable 。預設值:json 。 |
fields |
string |
否 | 選取器,用於指定要包含在回應中的欄位子集。 |
prettyPrint |
string |
否 |
傳回包含縮排和分行的回應。預設 false 。 |
userIp |
string |
否 | 指定發出 API 呼叫的使用者 IP 位址。 用於每個 IP 的用量上限。 |
quotaUser |
string |
否 | 如果使用者 IP 位址不明,則為 userIp 的替代項目。 |
access_token |
string |
否 | 提供 OAuth 2.0 權杖的其中一種方式。 |
callback |
string |
否 | 處理回應的 JavaScript 回呼函式名稱。用於 JavaScript JSON-P 要求。 |
key |
string |
否 | 用於 OAuth 1.0a 授權,用於指定取得配額的應用程式。例如:key=AldefliuhSFADSfasdfasdfASdf 。 |
查詢參數詳細資料
ids
ids=ga:12345
ga:
與 Analytics (分析) 資料檢視 (設定檔) ID 的串連。您可以使用 analytics.management.profiles.list
方法擷取資料檢視 (設定檔) ID,以便在 Google Analytics Management API 的檢視畫面 (設定檔) 資源中提供 id
。開始日期
start-date=2009-04-20
start-date
和 end-date
參數,伺服器會傳回錯誤。您可以使用模式 YYYY-MM-DD
或 today
、yesterday
或 NdaysAgo
模式,指定特定日期的日期值。值必須與 [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
相符。start-date
為 2005-01-01
。
開始日期沒有上限。使用相對日期最近 7 天 (從昨天開始) 的日期範圍範例:
&start-date=7daysAgo &end-date=yesterday
結束日期
end-date=2009-05-20
start-date
和 end-date
參數,伺服器會傳回錯誤。您可以使用模式 YYYY-MM-DD
或 today
、yesterday
或 NdaysAgo
模式,指定特定日期的日期值。值必須與 [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
相符。end-date
為 2005-01-01
。end-date
沒有上限。最近 10 天 (從今天開始) 的日期範圍範例:
&start-date=9daysAgo &end-date=today
尺寸
dimensions=ga:browser,ga:city
dimensions
參數會按照常見條件細分指標,例如 ga:browser
或 ga:city
。雖然您可以要求取得網站的總瀏覽量,但最好還是要求提供按瀏覽器細分的瀏覽量資料。在此情況下,您會看到來自 Firefox、Internet Explorer、Chrome 等的網頁瀏覽次數。
在資料要求中使用 dimensions
時,請注意下列限制:
- 每個查詢最多可提供 7 個維度。
- 您無法傳送僅由維度組成的查詢,您必須為任何要求的維度結合至少一項指標。
- 同一項查詢只能查詢特定維度。請使用 維度和指標參考資料中的有效組合工具,查看哪些維度可搭配使用。
metrics
metrics=ga:sessions,ga:bounces
dimensions
參數,傳回的指標會針對要求的日期範圍提供匯總值,例如整體網頁瀏覽或總跳出次數。但是,收到維度要求時,系統會按維度值區隔值。舉例來說,如果使用 ga:country
要求 ga:pageviews
,系統會傳回每個國家/地區的總網頁瀏覽量。要求取得指標時,請注意以下幾點:
- 每個要求都必須提供至少一個指標;要求不能僅包含維度。
- 每個查詢最多可提供 10 個指標。
- 如未指定維度,多個類別的指標組合都可以搭配使用。
- 指標可以與其他維度或指標搭配使用,但僅限於該指標適用的有效組合。 詳情請參閱維度和指標參考資料。
排序
sort=ga:country,ga:browser
指標和維度清單,表示傳回資料的排序順序和排序方向。
- 系統會依據所列出的指標和維度由左至右的順序指定「排序」。
- 「方向」direction排序預設為遞增,只要在要求欄位中加上減號 (
-
) 前置字串,即可變更為遞減。
將查詢結果排序,您就能針對資料提出不同的問題。舉例來說,如要解決「我最常使用哪些國家/地區?他們最常使用哪些瀏覽器?」這類問題,你可以使用下列參數執行查詢。其先按 ga:country
再按 ga:browser
排序,兩者皆以遞增順序排序:
sort=ga:country,ga:browser
如要回答「我最常使用哪些瀏覽器,以及哪些國家/地區最常使用?」這類問題,您可以使用下列參數執行查詢。這會先依
ga:browser
再按 ga:country
排序,兩者皆以遞增順序排序:sort=ga:browser,ga:country
使用 sort
參數時,請注意下列事項:
- 請僅依據您在
dimensions
或metrics
參數中使用的維度或指標值排序。如果要求排序的欄位沒有在維度或指標參數中指出,您就會收到錯誤訊息。 - 根據預設,字串會按照 en-US 語言代碼的字母順序遞增排序。
- 根據預設,數字會按遞增編號排序。
- 根據預設,日期會按照日期遞增排序。
篩選器
filters=ga:medium%3D%3Dreferral
filters
查詢字串參數會限制要求傳回的資料。如要使用 filters
參數,請提供要篩選的維度或指標,並在後面加上篩選器運算式。舉例來說,下列查詢要求檢視畫面 (設定檔) 12134
的 ga:pageviews
和 ga:browser
,其中 ga:browser
維度的開頭為 Firefox
字串:
https://www.googleapis.com/analytics/v3/data/ga ?ids=ga:12134 &dimensions=ga:browser &metrics=ga:pageviews &filters=ga:browser%3D~%5EFirefox &start-date=2007-01-01 &end-date=2007-12-31
查詢經過篩選,會限制能夠 (或未) 納入結果的資料列。結果中的每一列都會經過篩選器的測試:如果篩選器達成比對,系統會保留該列,比對不相符就捨棄該資料列。
- 網址編碼:Google API 用戶端程式庫會自動為篩選器運算子進行編碼。
- 維度篩選:篩選是在任何維度匯總「之前」進行的,因此傳回的指標只代表相關維度的總數。在上述範例中,網頁瀏覽量只包括在 Firefox 中做為瀏覽器的網頁瀏覽量。
- 指標篩選:在指標匯總「之後」,系統才會篩選指標。
- 有效組合:您可以篩選不屬於查詢的維度或指標,前提是要求中「而且」篩選器是有效組合。例如,您可能想要查詢特定日期的網頁瀏覽清單,並篩選特定瀏覽器。詳情請參閱維度和指標參考資料。
篩選器語法
單一篩選器的形式如下:
ga:name operator expression
在這個語法中:
- name:做為篩選依據的維度或指標名稱。例如:
ga:pageviews
篩選網頁瀏覽量指標。 - operator — 定義要使用的篩選器比對類型。運算子專用於維度或指標。
- expression - 指出結果中要包含或排除的值。運算式使用規則運算式語法。
篩選器運算子
維度有六種篩選運算子和六個篩選器運算子。運算子必須經過網址編碼才能納入網址查詢字串中。
提示:請使用資料動態饋給查詢探索工具設計需要網址編碼的篩選器,因為 Query Explorer 會自動為包含字串和空格的網址編碼。
運算子 | 說明 | 網址編碼格式 | 示例 |
---|---|---|---|
== |
等於 | %3D%3D |
傳回網頁時間完全符合 10 秒的結果:filters=ga:timeOnPage%3D%3D10 |
!= |
不等於 | !%3D |
傳回網頁停留時間「不是」10 秒的結果:filters=ga:timeOnPage!%3D10 |
> |
大於 | %3E |
傳回網頁時間大於 10 秒的結果:filters=ga:timeOnPage%3E10 |
< |
小於 | %3C |
傳回網頁時間小於 10 秒的結果:filters=ga:timeOnPage%3C10 |
>= |
大於或等於 | %3E%3D |
傳回網頁停留時間至少為 10 秒的結果:filters=ga:timeOnPage%3E%3D10 |
<= |
小於或等於 | %3C%3D |
傳回網頁停留時間在 10 秒以內的結果:filters=ga:timeOnPage%3C%3D10 |
運算子 | 說明 | 網址編碼格式 | 範例 |
---|---|---|---|
== |
完全比對 | %3D%3D |
匯總城市為 Irvine 的指標:filters=ga:city%3D%3DIrvine |
!= |
不相符 | !%3D |
匯總城市並非 爾灣的指標:filters=ga:city!%3DIrvine |
=@ |
包含子字串 | %3D@ |
匯總城市包含約克的指標:filters=ga:city%3D@York |
!@ |
不含子字串 | !@ |
匯總不含約克的城市指標:filters=ga:city!@York |
=~ |
與規則運算式相符 | %3D~ |
匯總城市以「New」開頭的指標:filters=ga:city%3D~%5ENew.* (%5E 是從 ^ 字元編碼的網址,固定字串的開頭有模式)。 |
!~ |
不符合規則運算式 | !~ |
匯總城市名稱開頭以外的值:filters=ga:city!~%5ENew.* |
篩選器運算式
篩選運算式有幾個重要規則:
- 網址保留字元 —
&
等字元必須以正常的方式進行網址編碼。 - 保留字元 — 當分號和逗號出現在運算式時,必須以反斜線逸出:
- 分號
\;
- 逗號
\,
- 分號
- 規則運算式:您也可以透過
=~
和!~
運算子,在篩選運算式中使用規則運算式。這類運算子的語法和 Perl 規則運算式類似,並且有以下額外規則:- 長度上限為 128 個字元:如果規則運算式長度超過 128 個字元,伺服器會傳回
400 Bad Request
狀態碼。 - 區分大小寫 - 規則運算式比對不區分大小寫。
- 長度上限為 128 個字元:如果規則運算式長度超過 128 個字元,伺服器會傳回
合併篩選器
篩選器可使用 OR
和 AND
布林邏輯合併。這樣一來,您就能有效延長篩選運算式 128 個字元的上限。
OR
OR
運算子是以半形逗號 (,
) 定義。
其優先順序高於 AND
運算子,且「不得」用於在同一個運算式中合併維度和指標。
範例: (每個都必須進行網址編碼)
國家/地區為 (美國或加拿大):
ga:country==United%20States,ga:country==Canada
Firefox 使用者 (Windows 或 Macintosh) 作業系統的使用者:
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh
及
AND
運算子是以分號 (;
) 開頭。
前方有 OR
運算子,而 CAN 可用來在同一個運算式中合併維度和指標。
範例: (每個都必須進行網址編碼)
國家/地區為美國,且瀏覽器為 Firefox:
ga:country==United%20States;ga:browser==Firefox
國家/地區為美國,且語言開頭不是「en」:
ga:country==United%20States;ga:language!~^en.*
作業系統為 (Windows 或 Macintosh)「且」瀏覽器為 (Firefox 或 Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome
國家/地區為美國「且」工作階段大於 5:
ga:country==United%20States;ga:sessions>5
區隔
segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
如需如何在 Core Reporting API 中要求區隔的完整詳細資料,請參閱區隔開發指南。
如需區隔的概念總覽,請參閱說明中心的「區隔功能參考資料」和「 區隔」說明文章。
區隔中允許的維度和指標。
只有部分維度和指標可用於區隔。如要查看區隔中可使用的維度和指標,請前往
Dimensions and Metrics Explorer。
samplingLevel
samplingLevel=DEFAULT
DEFAULT
:傳回樣本大小的回應,在速度和準確率之間取得平衡。FASTER
:傳回樣本大小較小的快速回應。HIGHER_PRECISION
:使用大型樣本大小傳回更準確的回應,但這可能會導致回應速度變慢。
DEFAULT
的取樣等級。包含空白資料列
include-empty-rows=true
起始索引
start-index=10
1
。(結果索引是從 1 開始)。也就是說,第一列是第 1
列,而不是第 0
列。如果 totalResults
超過 10,000,而您想擷取索引在 10,001 之後的資料列,請使用這個參數做為分頁機制和 max-results
參數。max-results
max-results=100
start-index
搭配使用來擷取元素子集,也可以單獨使用,藉此限制傳回的元素數量 (從第一個元素開始)。如未提供 max-results
,查詢會傳回預設最多 1000 個資料列。ga:country
的可能值少於 300 個,因此,如果只依國家/地區區隔資料,即使將 max-results
設為較高的值,也最多只能產生 300 列資料。output
output=dataTable
json
:在回應中輸出預設rows
屬性,其中包含 JSON 物件。dataTable
:在回應中輸出dataTable
屬性,其中包含 資料表物件。這個Data Table
物件可以直接與 Google Charts 圖表搭配使用。
欄位
fields=rows,columnHeaders(name,dataType)
指定要在部分回應中傳回的欄位。如果您只會在 API 回應中使用部分欄位,可以使用 fields
參數指定要包含的欄位。
欄位要求參數值的格式約略以 XPath 語法為基礎。支援的語法摘要如下。
- 使用以逗號分隔的清單來選取多個欄位。
- 使用
a/b
選取巢狀於欄位 a 中的欄位 b;使用a/b/c
選取巢狀結構中的 b 欄位 c。 - 透過在括號
"( )"
中放入運算式,使用子選取器來要求一組指定的陣列或物件子欄位。
例如:fields=columnHeaders(name,dataType)
只會傳回columnHeaders
陣列中的name
和dataType
欄位。您也可以指定單一子欄位,其中fields=columnHeader(name)
等於fields=columnHeader/name
。
prettyPrint
prettyPrint=false
如果為 true
,則以使用者可理解的格式傳回回應。
預設值為 false
。
quotaUser
quotaUser=4kh4r2h4
讓您在使用者 IP 位址不明的情況下,也能透過伺服器端的應用程式 強制執行每個使用者的配額。舉例來說,如果應用程式代表使用者在 App Engine 上執行 Cron 工作,就可能會發生這種情況。您可以選擇專門用來識別使用者的任意字串,但上限為 40 個字元。
如果兩者都提供,就會覆寫 userIp
。
回應
如果成功,這項要求就會傳回如下定義的 JSON 結構的回應主體。如果將 output 參數設為 dataTable
,要求會傳回具有以下定義的 JSON (資料表) 結構的回應主體。
注意事項:「結果」一詞是指符合查詢的整組資料列,而「回應」則是指目前結果頁面上傳回的一組資料列。如果結果總數大於目前回應的頁面大小,則結果可能會有所不同,詳情請參閱 itemsPerPage 頁面。
{
"kind": "analytics#gaData",
"id": string,
"selfLink": string,
"containsSampledData": boolean,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"include-empty-rows": boolean
"samplingLevel": string,
"sort": [
string
],
"filters": string,
"segment": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"rows": [
[
string
]
],
"sampleSize": string,
"sampleSpace": string,
"totalsForAllResults": [
{
metricName: string,
...
}
]
}
回應欄位
回應主體結構的屬性定義如下:
資源名稱 | 值 | 說明 |
---|---|---|
kind |
string |
資源類型。值為「analytics#gaData」。 |
id |
string |
此資料回應的 ID。 |
query |
object |
這個物件包含以參數形式傳送至查詢的所有值。每個欄位的意義都有對應查詢參數的說明。 |
query.start-date |
string |
開始日期。 |
query.end-date |
string |
結束日期。 |
query.ids |
string |
不重複的資料表 ID。 |
query.dimensions[] |
list |
數據分析維度清單。 |
query.metrics[] |
list |
數據分析指標清單。 |
query.samplingLevel |
string |
Requested sampling level. |
query.include-empty-rows |
boolean |
預設值為 true;如果設為 False,回應會略過所有指標值皆為零的資料列。 |
query.sort[] |
list |
資料排序依據的指標或維度清單。 |
query.filters |
string |
以半形逗號分隔的指標或維度篩選器清單。 |
query.segment |
string |
Analytics (分析) 區隔。 |
query.start-index |
integer |
開始索引。 |
query.max-results |
integer |
每頁結果數量上限。 |
startIndex |
integer |
start-index 查詢參數指定資料列的起始索引。預設值為 1。 |
itemsPerPage |
integer |
回應可包含的資料列數量上限,無論傳回的實際資料列數為何。如果指定 max-results 查詢參數,則 itemsPerPage 的值會是 max-results 或 10,000 的較小值。itemsPerPage 的預設值為 1000。 |
totalResults |
integer |
查詢結果中的資料列總數,無論回應中傳回的資料列數為何。如果查詢會產生大量資料列,totalResults 可以大於 itemsPerPage 。如要進一步瞭解大型查詢的 totalResults 和 itemsPerPage ,請參閱 Paging。 |
startDate |
string |
資料查詢的開始日期,如 start-date 參數所指定。 |
endDate |
string |
資料查詢的結束日期,由 end-date 參數指定。 |
selfLink |
string |
這個資料查詢的結果頁面連結。 |
previousLink |
string |
連結至這個資料查詢的上一頁。 |
nextLink |
string |
這個資料查詢的結果下一頁連結。 |
profileInfo |
object |
要求取得資料的資料檢視 (設定檔) 的相關資訊。您可以透過 Google Analytics Management API 取得資料檢視 (設定檔) 資料。 |
profileInfo.profileId |
string |
資料檢視 (設定檔) ID,例如 1174 。 |
profileInfo.accountId |
string |
這個資料檢視 (設定檔) 所屬的帳戶 ID,例如 30481 。 |
profileInfo.webPropertyId |
string |
此資料檢視 (設定檔) 所屬的網站資源 ID,例如 UA-30481-1 。 |
profileInfo.internalWebPropertyId |
string |
這個資料檢視 (設定檔) 所屬網站資源的內部編號,例如 UA-30481-1 。 |
profileInfo.profileName |
string |
資料檢視 (設定檔) 的名稱。 |
profileInfo.tableId |
string |
資料檢視 (設定檔) 的資料表 ID,由「ga:」組成,後面接上資料檢視 (設定檔) ID。 |
containsSampledData |
boolean |
如果回應包含取樣資料,則為 True。 |
sampleSize |
string |
用來計算取樣資料的樣本數。 |
sampleSpace |
string |
取樣空間總大小。這代表已選取樣本的可用樣本空間總大小。 |
columnHeaders[] |
list |
列出維度名稱後方的欄標題。維度和指標的順序與透過 metrics 和 dimensions 參數在要求中指定的順序相同。標頭數量是指維度數量 + 指標數量。 |
columnHeaders[].name |
string |
維度或指標的名稱。 |
columnHeaders[].columnType |
string |
資料欄類型。「DIMENSION」或「METRIC」。 |
columnHeaders[].dataType |
string |
資料類型。維度欄標題只有「STRING 」做為資料類型。指標欄標題含有指標值的資料類型,例如 INTEGER 、PERCENT 、TIME 、CURRENCY 、FLOAT 等。如要瞭解所有可能的資料類型,請參閱 metadata API 回應。 |
totalsForAllResults |
object |
要求指標的總值,做為指標名稱和值的鍵/值組合。指標總數的順序與要求中指定的指標順序相同。 |
rows[] |
list |
Analytics (分析) 資料列,其中每一列都包含維度值清單,後面接著指標值。維度和指標的順序與要求中指定的順序相同。每個資料列都有 N 個欄位清單,其中 N = 維度數量 + 指標數量。 |
{
"kind": "analytics#gaData",
"id": string,
"selfLink": string,
"containsSampledData": boolean,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"samplingLevel": string,
"include-empty-rows": boolean,
"sort": [
string
],
"filters": string,
"segment": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"dataTable": {
"cols": [
{
"id": string,
"label": string,
"type": string
}
],
"rows": [
{
"c": [
{
"v": string
}
]
}
]
},
"sampleSize": string,
"sampleSpace": string,
"totalsForAllResults": [
{
metricName: string,
...
}
]
}
回應欄位
回應主體結構的屬性定義如下:
資源名稱 | 值 | 說明 |
---|---|---|
kind |
string |
資源類型。值為「analytics#gaData」。 |
id |
string |
此資料回應的 ID。 |
query |
object |
這個物件包含以參數形式傳送至查詢的所有值。每個欄位的意義都有對應查詢參數的說明。 |
query.start-date |
string |
開始日期。 |
query.end-date |
string |
結束日期。 |
query.ids |
string |
不重複的資料表 ID。 |
query.dimensions[] |
list |
數據分析維度清單。 |
query.metrics[] |
list |
數據分析指標清單。 |
query.samplingLevel |
string |
Requested sampling level. |
query.include-empty-rows |
boolean |
預設值為 true;如果設為 False,回應會略過所有指標值皆為零的資料列。 |
query.sort[] |
list |
資料排序依據的指標或維度清單。 |
query.filters |
string |
以半形逗號分隔的指標或維度篩選器清單。 |
query.segment |
string |
Analytics (分析) 區隔。 |
query.start-index |
integer |
開始索引。 |
query.max-results |
integer |
每頁結果數量上限。 |
startIndex |
integer |
start-index 查詢參數指定資料列的起始索引。預設值為 1。 |
itemsPerPage |
integer |
回應可包含的資料列數量上限,無論傳回的實際資料列數為何。如果指定 max-results 查詢參數,則 itemsPerPage 的值會是 max-results 或 10,000 的較小值。itemsPerPage 的預設值為 1000。 |
totalResults |
integer |
查詢結果中的資料列總數,無論回應中傳回的資料列數為何。如果查詢會產生大量資料列,totalResults 可以大於 itemsPerPage 。如要進一步瞭解大型查詢的 totalResults 和 itemsPerPage ,請參閱 Paging。 |
startDate |
string |
資料查詢的開始日期,如 start-date 參數所指定。 |
endDate |
string |
資料查詢的結束日期,由 end-date 參數指定。 |
selfLink |
string |
這個資料查詢的結果頁面連結。 |
previousLink |
string |
連結至這個資料查詢的上一頁。 |
nextLink |
string |
這個資料查詢的結果下一頁連結。 |
profileInfo |
object |
要求取得資料的資料檢視 (設定檔) 的相關資訊。您可以透過 Google Analytics Management API 取得資料檢視 (設定檔) 資料。 |
profileInfo.profileId |
string |
資料檢視 (設定檔) ID,例如 1174 。 |
profileInfo.accountId |
string |
這個資料檢視 (設定檔) 所屬的帳戶 ID,例如 30481 。 |
profileInfo.webPropertyId |
string |
此資料檢視 (設定檔) 所屬的網站資源 ID,例如 UA-30481-1 。 |
profileInfo.internalWebPropertyId |
string |
這個資料檢視 (設定檔) 所屬網站資源的內部編號,例如 UA-30481-1 。 |
profileInfo.profileName |
string |
資料檢視 (設定檔) 的名稱。 |
profileInfo.tableId |
string |
資料檢視 (設定檔) 的資料表 ID,由「ga:」組成,後面接上資料檢視 (設定檔) ID。 |
containsSampledData |
boolean |
如果回應包含取樣資料,則為 True。 |
sampleSize |
string |
用來計算取樣資料的樣本數。 |
sampleSpace |
string |
取樣空間總大小。這代表已選取樣本的可用樣本空間總大小。 |
columnHeaders[] |
list |
列出維度名稱後方的欄標題。維度和指標的順序與透過 metrics 和 dimensions 參數在要求中指定的順序相同。標頭數量是指維度數量 + 指標數量。 |
columnHeaders[].name |
string |
維度或指標的名稱。 |
columnHeaders[].columnType |
string |
資料欄類型。「DIMENSION」或「METRIC」。 |
columnHeaders[].dataType |
string |
資料類型。維度欄標題只有「STRING 」做為資料類型。指標欄標題含有指標值的資料類型,例如 INTEGER 、PERCENT 、TIME 、CURRENCY 、FLOAT 等。如要瞭解所有可能的資料類型,請參閱 metadata API 回應。 |
totalsForAllResults |
object |
要求指標的總值,做為指標名稱和值的鍵/值組合。指標總數的順序與要求中指定的指標順序相同。 |
dataTable |
object |
可與 Google 圖表搭配使用的資料表物件。 |
dataTable.cols[] |
list |
指標後接指標的資料欄描述元清單。維度和指標的順序與透過 metrics 和 dimensions 參數在要求中指定的順序相同。欄數是維度數量 + 指標數量。 |
dataTable.cols[].id |
string |
ID,可用來參照特定資料欄 (除了使用資料欄索引的替代方案)。維度或指標 ID 可用來設定這個值。 |
dataTable.cols[].label |
string |
資料欄的標籤 (可能會顯示於圖表)。維度或指標 ID 可用來設定這個值。 |
dataTable.cols[].type |
string |
這個資料欄的資料類型。 |
dataTable.rows[] |
list |
資料表格格式的 Analytics (分析) 資料列,其中每一列都是物件,內含維度和指標的儲存格值清單。維度和指標的順序與要求中指定的順序相同。每個儲存格都有一個 N 欄位清單,其中 N = 維度數量 + 指標數量。 |
錯誤代碼
如果要求成功,Core Reporting API 會傳回 200
HTTP 狀態碼。如果處理查詢時發生錯誤,API 會傳回錯誤代碼和說明。每個使用 Analytics API 的應用程式都必須導入適當的錯誤處理邏輯。如要進一步瞭解錯誤代碼及其處理方式,請參閱
錯誤回應參考指南。
歡迎試用!
您可以嘗試透過 Core Reporting API 執行查詢。
-
如要在查詢中查看有效的指標和維度組合,請在查詢探索工具中輸入參數的範例值。範例查詢結果會以資料表形式顯示,內含所有指定指標和維度的值。
-
如要對即時資料提出要求,並查看 JSON 格式的回應,請嘗試在 Google Data APIs Explorer 中使用
analytics.data.ga.get
方法。
取樣
Google Analytics (分析) 會即時計算特定維度和指標的組合。為了在合理的時間內傳回資料,Google Analytics (分析) 可能只會處理資料樣本。
您可以設定 samplingLevel 參數,指定要求的取樣等級。
如果 Core Reporting API 回應包含取樣資料,則 containsSampledData
回應欄位為 true
。此外,有 2 項屬性將提供查詢的取樣層級相關資訊:sampleSize
和 sampleSpace
。您可以利用這 2 個值,計算用於查詢的工作階段百分比。舉例來說,如果 sampleSize
是 201,000
而 sampleSpace
是 220,000
,則報表會以 (201,000 / 220,000) * 100 = 91.36% 的工作階段為依據。
如需取樣的一般說明及在 Google Analytics (分析) 中的使用方式,請參閱取樣一文。
處理大型資料結果
如果您預期查詢會傳回大型結果集,請參考下方指南協助您最佳化 API 查詢、避免錯誤,並將配額超額降到最低。請注意,為了設定效能基準,每個 API 要求最多可允許 7 個維度和 10 個指標。雖然某些指定大量指標和維度的查詢可能需要較長的處理時間,但限制要求的指標數量可能不足以改善查詢效能。建議您改用下列技巧,獲得最佳效能結果。
減少每次查詢的維度
API 可讓您在任何請求中指定最多 7 個維度。 很多時候,Google Analytics (分析) 必須即時計算這些複雜查詢結果。如果產生的資料列數量偏高,可能相當耗時。舉例來說,按城市 (按城市劃分) 查詢關鍵字,可能會符合數百萬列的資料。您可以限制查詢中的維度數量,減少 Google Analytics (分析) 需要處理的資料列數量,藉此提升效能。
按日期範圍拆分查詢
請考慮一次處理一週 (甚至是一天) 的個別查詢,而不是逐頁瀏覽某個較長的日期範圍 (以日期表示) 的結果。當然,對於大型資料集,即使要求的是一天資料,系統也可能傳回超過 max-results
,這時無法避免分頁。但在任何情況下,如果查詢的相符資料列數高於 max-results
,則分隔日期範圍可能會減少擷取結果的總時間。這個方法可以改善單一執行緒和平行查詢的效能。
Paging
逐頁瀏覽結果是將大型結果集分成多個可管理區塊的實用方法。totalResults
欄位會顯示相符的資料列數量,itemsPerPage
則提供結果中可獲得的資料列數量上限。如果 totalResults
到 itemsPerPage
的比例很高,則個別查詢的處理時間可能會超過必要。如果您只需要少量的資料列 (例如為了顯示用途),透過 max-results
參數設定明確的回應大小限制會比較方便。不過,如果您的應用程式需要處理大量的大量結果,則要求允許的資料列數量上限可能更有效率。
使用 gzip
如果想要減少每個要求所需的頻寬,最簡單的方法就是啟用 gzip 壓縮。雖然此方法需要額外的 CPU 時間解壓縮結果,但相對可省下網路費用。如要接收以 gzip 編碼的回應,您必須執行下列兩項操作:設定 Accept-Encoding
標頭,並修改使用者代理程式來加入 gzip
字串。以下是啟用 gzip 壓縮的正確 HTTP 標頭格式範例:
Accept-Encoding: gzip User-Agent: my program (gzip)