Tài liệu này cung cấp tài liệu tham khảo đầy đủ cho cả truy vấn và phản hồi cho API Báo cáo chính phiên bản 3.0.
Giới thiệu
Bạn truy vấn API Báo cáo chính cho dữ liệu báo cáo Google Analytics. Mỗi truy vấn đều phải có mã chế độ xem (hồ sơ), ngày bắt đầu và ngày kết thúc cũng như ít nhất một chỉ số. Bạn cũng có thể cung cấp thêm tham số truy vấn như phương diện, bộ lọc và phân đoạn để tinh chỉnh cụm từ tìm kiếm của mình. Hãy xem Hướng dẫn tổng quan để hiểu cách tất cả các khái niệm này hoạt động cùng nhau.
Yêu cầu
API cung cấp một phương thức duy nhất để yêu cầu dữ liệu:
analytics.data.ga.get()
Phương thức này được hiển thị trong nhiều thư viện ứng dụng và có giao diện dành riêng cho ngôn ngữ để đặt tham số truy vấn.
API này cũng có thể được truy vấn dưới dạng một điểm cuối REST-ful:
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
Mỗi tham số truy vấn URL chỉ định một tham số truy vấn API phải được mã hoá URL.
Tóm tắt về tham số truy vấn
Bảng sau đây tóm tắt tất cả các tham số truy vấn được API Báo cáo chính chấp nhận. Nhấp vào tên của từng thông số để xem nội dung mô tả chi tiết.
Tên | Giá trị | Bắt buộc | Tóm tắt |
---|---|---|---|
ids |
string |
có | Mã bảng duy nhất của biểu mẫu ga:XXXX, trong đó XXXX là mã chế độ xem (hồ sơ) Analytics mà truy vấn sẽ truy xuất dữ liệu. |
start-date |
string |
có |
Ngày bắt đầu tìm nạp dữ liệu Analytics. Các yêu cầu có thể chỉ định ngày bắt đầu có định dạng là YYYY-MM-DD hoặc là ngày tương đối (ví dụ: today , yesterday hoặc NdaysAgo , trong đó N là số nguyên dương).
|
end-date |
string |
có |
Ngày kết thúc tìm nạp dữ liệu Analytics. Yêu cầu có thể chỉ định ngày kết thúc có định dạng YYYY-MM-DD hoặc là ngày tương đối (ví dụ:
today , yesterday hoặc NdaysAgo , trong đó N là số nguyên dương).
|
metrics |
string |
có |
Danh sách các chỉ số được phân tách bằng dấu phẩy, chẳng hạn như ga:sessions,ga:bounces .
|
dimensions |
string |
no |
Danh sách các phương diện được phân tách bằng dấu phẩy dành cho dữ liệu Analytics, chẳng hạn như
ga:browser,ga:city .
|
sort |
string |
no | Danh sách các phương diện và chỉ số được phân tách bằng dấu phẩy cho biết thứ tự sắp xếp và hướng sắp xếp của dữ liệu được trả về. |
filters |
string |
no | Những bộ lọc phương diện hoặc chỉ số hạn chế dữ liệu được trả về cho yêu cầu của bạn. |
segment |
string |
no | Phân đoạn dữ liệu được trả về cho yêu cầu của bạn. |
samplingLevel |
string |
no | Mức lấy mẫu mong muốn. Giá trị được phép:
|
include-empty-rows |
boolean |
no | Giá trị mặc định là đúng; nếu đặt thành false, thì các hàng có tất cả giá trị chỉ số bằng 0 sẽ bị loại khỏi phản hồi. |
start-index |
integer |
no |
Hàng dữ liệu đầu tiên cần truy xuất,
bắt đầu từ 1. Hãy dùng tham số này làm cơ chế phân trang cùng với tham số max-results .
|
max-results |
integer |
no | Số hàng tối đa có thể đưa vào phản hồi. |
output |
string |
no |
Loại đầu ra mong muốn cho dữ liệu Analytics được trả về trong phản hồi.
Các giá trị được chấp nhận là json và dataTable . Mặc định: json .
|
fields |
string |
no | Bộ chọn chỉ định một tập hợp con các trường để đưa vào phản hồi. |
prettyPrint |
string |
no |
Trả về phản hồi có thụt đầu dòng và ngắt dòng. false mặc định.
|
userIp |
string |
no | Chỉ định địa chỉ IP của người dùng cuối đang thực hiện lệnh gọi API. Dùng để giới hạn mức sử dụng trên mỗi IP. |
quotaUser |
string |
no | Thay thế cho userIp trong trường hợp địa chỉ IP của người dùng không xác định. |
access_token |
string |
no | Bạn có thể cung cấp mã thông báo OAuth 2.0. |
callback |
string |
no | Tên của hàm callback JavaScript xử lý phản hồi. Dùng trong yêu cầu JavaScript JSON-P. |
key |
string |
no | Dùng cho hoạt động uỷ quyền OAuth 1.0a để chỉ định ứng dụng nhận hạn mức. Ví dụ: key=AldefliuhSFADSfasdfasdfASdf . |
Chi tiết tham số truy vấn
ids
ids=ga:12345
ga:
với
mã chế độ xem (hồ sơ) Analytics. Bạn có thể truy xuất mã chế độ xem (hồ sơ) bằng cách sử dụng
phương thức analytics.management.profiles.list
. Phương thức này cung cấp id
trong tài nguyên Chế độ xem (Hồ sơ)
trong
API Quản lý
Google Analytics.
ngày bắt đầu
start-date=2009-04-20
start-date
và end-date
vào yêu cầu, thì máy chủ sẽ trả về
lỗi. Bạn có thể đặt giá trị ngày cho một ngày cụ thể bằng mẫu YYYY-MM-DD
hoặc mẫu tương đối bằng cách sử dụng today
, yesterday
hoặc NdaysAgo
.
Giá trị phải khớp với
[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
.
start-date
hợp lệ sớm nhất là 2005-01-01
.
Không có giới hạn giới hạn trên cho ngày bắt đầu.Ví dụ về phạm vi ngày trong 7 ngày qua (bắt đầu từ hôm qua) sử dụng ngày tương đối:
&start-date=7daysAgo &end-date=yesterday
ngày kết thúc
end-date=2009-05-20
start-date
và end-date
vào yêu cầu, thì máy chủ sẽ trả về
lỗi. Bạn có thể đặt giá trị ngày cho một ngày cụ thể bằng mẫu YYYY-MM-DD
hoặc mẫu tương đối bằng cách sử dụng today
, yesterday
hoặc NdaysAgo
.
Giá trị phải khớp với
[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
.
end-date
hợp lệ sớm nhất là
2005-01-01
. Không có giới hạn giới hạn trên đối với end-date
. Ví dụ về phạm vi ngày trong 10 ngày qua (bắt đầu từ hôm nay) sử dụng ngày tương đối:
&start-date=9daysAgo &end-date=today
phương diện
dimensions=ga:browser,ga:city
dimensions
chia nhỏ các chỉ số theo các tiêu chí phổ biến; ví dụ: theo ga:browser
hoặc ga:city
.
Mặc dù bạn có thể hỏi về tổng số lượt xem trang trên trang web của mình, nhưng bạn nên hỏi về số lượt xem trang phân chia theo trình duyệt. Trong trường hợp này, bạn sẽ thấy số lượt xem trang trên Firefox, Internet Explorer, Chrome, v.v.
Khi sử dụng dimensions
trong một yêu cầu dữ liệu, hãy lưu ý các hạn chế sau:
- Bạn có thể cung cấp tối đa 7 phương diện trong bất kỳ truy vấn nào.
- Bạn không thể gửi một truy vấn chỉ gồm các phương diện: bạn phải kết hợp mọi phương diện được yêu cầu với ít nhất một chỉ số.
- Bạn chỉ có thể truy vấn một số phương diện nhất định trong cùng một truy vấn. Hãy sử dụng công cụ kết hợp hợp lệ trong Tài liệu tham khảo về phương diện và chỉ số để xem những phương diện có thể sử dụng cùng nhau.
metrics
metrics=ga:sessions,ga:bounces
dimensions
, thì chỉ số được trả về sẽ cung cấp các giá trị tổng hợp cho phạm vi ngày được yêu cầu, chẳng hạn như tổng số lượt xem trang hoặc tổng số trang không truy cập. Tuy nhiên, khi
phương diện được yêu cầu, các giá trị sẽ được phân đoạn theo giá trị
phương diện. Ví dụ: trường hợp ga:pageviews
được yêu cầu cùng với
ga:country
sẽ trả về tổng số lượt xem trang trên mỗi quốc gia.
Khi yêu cầu chỉ số, hãy lưu ý:
- Mỗi yêu cầu đều phải cung cấp ít nhất một chỉ số; một yêu cầu không thể chỉ bao gồm các phương diện.
- Bạn có thể cung cấp tối đa 10 chỉ số cho bất kỳ truy vấn nào.
- Bạn có thể sử dụng hầu hết các tổ hợp chỉ số thuộc nhiều danh mục, miễn là không có phương diện nào được chỉ định.
- Một chỉ số có thể được sử dụng kết hợp với các phương diện hoặc chỉ số khác, nhưng chỉ khi có các cách kết hợp hợp lệ cho chỉ số đó. Hãy xem Tài liệu tham khảo về phương diện và chỉ số để biết thêm chi tiết.
sắp xếp
sort=ga:country,ga:browser
Danh sách các chỉ số và phương diện cho biết thứ tự sắp xếp và hướng sắp xếp của dữ liệu được trả về.
- Thứ tự sắp xếp được chỉ định theo thứ tự từ trái sang phải của các chỉ số và phương diện được liệt kê.
- direction sắp xếp mặc định là tăng dần và bạn có thể thay đổi thành giảm dần bằng cách sử dụng tiền tố dấu trừ (
-
) trên trường được yêu cầu.
Việc sắp xếp kết quả của một truy vấn cho phép bạn đặt nhiều câu hỏi về dữ liệu của mình. Ví dụ: để giải đáp câu hỏi "Các quốc gia hàng đầu của tôi là gì và họ sử dụng trình duyệt nào nhiều nhất?"
bạn có thể tạo truy vấn bằng thông số sau. Trước tiên, trình bổ trợ này sẽ sắp xếp theo ga:country
, sau đó là ga:browser
, cả hai đều theo thứ tự tăng dần:
sort=ga:country,ga:browser
Để trả lời câu hỏi liên quan "Trình duyệt hàng đầu của tôi là những trình duyệt nào và những quốc gia nào sử dụng trình duyệt đó nhiều nhất?", bạn có thể truy vấn bằng tham số sau. Trước tiên, trình phân tích này sẽ sắp xếp theo
ga:browser
, sau đó là ga:country
, cả hai đều theo thứ tự tăng dần:sort=ga:browser,ga:country
Khi sử dụng tham số sort
, hãy lưu ý những điều sau:
- Chỉ sắp xếp theo những phương diện hoặc giá trị chỉ số mà bạn đã sử dụng trong thông số
dimensions
hoặcmetrics
. Nếu yêu cầu của bạn sắp xếp trên một trường không được biểu thị trong thông số phương diện hoặc chỉ số, thì bạn sẽ gặp lỗi. - Theo mặc định, các chuỗi được sắp xếp theo thứ tự bảng chữ cái tăng dần trong ngôn ngữ en-US.
- Theo mặc định, các số được sắp xếp theo thứ tự số tăng dần.
- Theo mặc định, ngày được sắp xếp theo thứ tự tăng dần theo ngày.
bộ lọc
filters=ga:medium%3D%3Dreferral
Tham số chuỗi truy vấn filters
hạn chế dữ liệu trả về từ yêu cầu của bạn. Để sử dụng tham số filters
, hãy cung cấp phương diện hoặc chỉ số cần lọc, theo sau là
biểu thức lọc. Ví dụ: truy vấn sau đây yêu cầu ga:pageviews
và ga:browser
cho chế độ xem (hồ sơ) 12134
, trong đó phương diện ga:browser
bắt đầu bằng chuỗi 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
Truy vấn được lọc sẽ hạn chế những hàng có (hoặc không) được đưa vào kết quả. Mỗi hàng trong kết quả sẽ được kiểm tra dựa trên bộ lọc: nếu bộ lọc khớp, hàng sẽ được giữ lại và nếu không khớp, hàng sẽ bị loại bỏ.
- Mã hoá URL: Thư viện ứng dụng API của Google tự động mã hoá các toán tử của bộ lọc.
- Lọc phương diện: Quá trình lọc diễn ra trước khi bất kỳ phương diện nào được tổng hợp để các chỉ số được trả về chỉ đại diện cho tổng số của các phương diện có liên quan. Trong ví dụ trên, số lượt xem trang chỉ là những lượt xem trang khi Firefox là trình duyệt.
- Lọc chỉ số: Việc lọc theo các chỉ số diễn ra sau khi các chỉ số được tổng hợp.
- Kết hợp hợp lệ: Bạn có thể lọc ra một phương diện hoặc chỉ số không thuộc truy vấn của bạn, miễn là tất cả các phương diện/chỉ số trong yêu cầu và bộ lọc là cách kết hợp hợp lệ. Ví dụ: bạn có thể truy vấn danh sách lượt xem trang theo ngày, lọc trên một trình duyệt cụ thể. Hãy xem Tài liệu tham khảo về phương diện và chỉ số để biết thêm thông tin.
Cú pháp bộ lọc
Một bộ lọc sử dụng biểu mẫu:
ga:name operator expression
Trong cú pháp sau:
- name — tên của phương diện hoặc chỉ số cần lọc. Ví dụ:
ga:pageviews
lọc chỉ số lượt xem trang. - toán tử — xác định loại bộ lọc phù hợp cần sử dụng. Toán tử cụ thể cho thứ nguyên hoặc chỉ số.
- biểu thức – cho biết các giá trị cần được đưa vào hoặc bị loại trừ khỏi kết quả. Biểu thức sử dụng cú pháp biểu thức chính quy.
Toán tử bộ lọc
Có 6 toán tử lọc cho các phương diện và 6 toán tử lọc cho chỉ số. Các toán tử phải được mã hoá URL để có thể được đưa vào chuỗi truy vấn URL.
Mẹo: Sử dụng Trình khám phá truy vấn nguồn cấp dữ liệu để thiết kế bộ lọc cần mã hoá URL, vì Trình khám phá truy vấn tự động mã hoá URL chứa chuỗi và dấu cách.
Đơn vị tổ chức | Nội dung mô tả | Biểu mẫu được mã hoá URL | Ví dụ |
---|---|---|---|
== |
Bằng | %3D%3D |
Trả về những kết quả có thời gian trên trang chính xác là 10 giây:filters=ga:timeOnPage%3D%3D10 |
!= |
Không bằng | !%3D |
Trả về những kết quả trong đó thời gian trên trang không phải là 10 giây:filters=ga:timeOnPage!%3D10 |
> |
Lớn hơn | %3E |
Trả về những kết quả có thời gian trên trang lớn hơn 10 giây:filters=ga:timeOnPage%3E10 |
< |
Nhỏ hơn | %3C |
Trả về những kết quả có thời gian trên trang hoàn toàn dưới 10 giây:filters=ga:timeOnPage%3C10 |
>= |
Lớn hơn hoặc bằng | %3E%3D |
Trả về những kết quả có thời gian trên trang từ 10 giây trở lên:filters=ga:timeOnPage%3E%3D10 |
<= |
Ít hơn hoặc bằng | %3C%3D |
Trả về những kết quả có thời gian trên trang từ 10 giây trở xuống:filters=ga:timeOnPage%3C%3D10 |
Đơn vị tổ chức | Nội dung mô tả | Biểu mẫu được mã hoá URL | Ví dụ: |
---|---|---|---|
== |
Khớp chính xác | %3D%3D |
Các chỉ số tổng hợp có thành phố là Irvine:filters=ga:city%3D%3DIrvine |
!= |
Không khớp | !%3D |
Chỉ số tổng hợp mà thành phố không phải là Irvine:filters=ga:city!%3DIrvine |
=@ |
Chứa chuỗi con | %3D@ |
Các chỉ số tổng hợp nơi thành phố đó có chứa Israel:filters=ga:city%3D@York |
!@ |
Không chứa chuỗi con | !@ |
Các chỉ số tổng hợp nơi thành phố không chứa Israel:filters=ga:city!@York |
=~ |
Chứa kết quả phù hợp cho biểu thức chính quy | %3D~ |
Tổng hợp các chỉ số tổng hợp mà thành phố bắt đầu bằng Mới:filters=ga:city%3D~%5ENew.* (%5E là URL được mã hoá từ ký tự ^ liên kết một mẫu đến đầu chuỗi.) |
!~ |
Không khớp với cụm từ thông dụng | !~ |
Các chỉ số tổng hợp mà thành phố không bắt đầu bằng Mới: filters=ga:city!~%5ENew.* |
Biểu thức bộ lọc
Có một số quy tắc quan trọng đối với biểu thức lọc:
- Ký tự dành riêng cho URL — Các ký tự như
&
phải được mã hoá url theo cách thông thường. - Ký tự đặt trước – Dấu chấm phẩy và dấu phẩy phải là dấu gạch chéo ngược xuất hiện trong một biểu thức:
- dấu chấm phẩy
\;
- dấu phẩy
\,
- dấu chấm phẩy
- Biểu thức chính quy – Bạn cũng có thể sử dụng biểu thức chính quy trong biểu thức lọc bằng toán tử
=~
và!~
. Cú pháp của biểu thức chính quy Perl cũng tương tự như biểu thức chính quy Perl và có thêm các quy tắc sau:- Độ dài tối đa 128 ký tự – Biểu thức chính quy dài hơn 128 ký tự sẽ dẫn đến mã trạng thái
400 Bad Request
do máy chủ trả về. - Phân biệt chữ hoa chữ thường – Việc so khớp biểu thức chính quy không phân biệt chữ hoa chữ thường.
- Độ dài tối đa 128 ký tự – Biểu thức chính quy dài hơn 128 ký tự sẽ dẫn đến mã trạng thái
Kết hợp các bộ lọc
Bạn có thể kết hợp các bộ lọc bằng cách sử dụng logic boolean OR
và AND
. Thao tác này cho phép bạn mở rộng giới hạn 128 ký tự của một biểu thức lọc một cách hiệu quả.
OR
Toán tử OR
được xác định bằng dấu phẩy (,
).
Toán tử này được ưu tiên hơn toán tử AND
và KHÔNG được sử dụng
để kết hợp phương diện và chỉ số trong cùng một biểu thức.
Ví dụ: (mỗi thông tin phải được mã hoá URL)
Quốc gia là (Hoa Kỳ HOẶC Canada):
ga:country==United%20States,ga:country==Canada
Người dùng Firefox sử dụng hệ điều hành (Windows HOẶC Macintosh):
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh
VÀ
Toán tử AND
được xác định bằng dấu chấm phẩy (;
).
Đứng sau toán tử OR
và CAN dùng để kết hợp
các phương diện và chỉ số trong cùng một biểu thức.
Ví dụ: (mỗi thông tin phải được mã hoá URL)
Quốc gia là Hoa Kỳ VÀ trình duyệt là Firefox:
ga:country==United%20States;ga:browser==Firefox
Quốc gia là Hoa Kỳ VÀ ngôn ngữ không bắt đầu bằng "en":
ga:country==United%20States;ga:language!~^en.*
Hệ điều hành là (Windows HOẶC Macintosh) VÀ trình duyệt là (Firefox HOẶC Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome
Quốc gia là Hoa Kỳ VÀ số phiên lớn hơn 5:
ga:country==United%20States;ga:sessions>5
phân khúc
segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
Để biết đầy đủ thông tin chi tiết về cách yêu cầu một phân khúc trong API báo cáo chính, hãy xem Hướng dẫn phát triển phân khúc.
Để có tổng quan khái niệm về phân đoạn, hãy xem Tham khảo tính năng phân đoạn và Phân đoạn trong Trung tâm trợ giúp.
Các phương diện và chỉ số được phép sử dụng trong
phân khúc.
Không phải phương diện và chỉ số nào cũng có thể sử dụng được trong phân đoạn. Để xem xét
những phương diện và chỉ số được phép sử dụng trong phân khúc, hãy truy cập vào
Trình khám phá phương diện và chỉ số.
samplingLevel
samplingLevel=DEFAULT
DEFAULT
– Trả về phản hồi có kích thước mẫu cân bằng giữa tốc độ và độ chính xác.FASTER
– Trả về câu trả lời nhanh với kích thước mẫu nhỏ hơn.HIGHER_PRECISION
– Trả về phản hồi chính xác hơn bằng cách sử dụng một cỡ mẫu lớn, nhưng điều này có thể khiến phản hồi chậm hơn.
DEFAULT
sẽ được
sử dụng.hàng-bao-gồm-trống
include-empty-rows=true
start-index
start-index=10
1
. (Chỉ mục kết quả dựa trên số 1. Tức là hàng đầu tiên là hàng 1
, không phải hàng 0
.) Hãy sử dụng tham số này làm cơ chế phân trang cùng với tham số max-results
trong trường hợp totalResults
vượt quá 10.000 và bạn muốn truy xuất các hàng được lập chỉ mục tại 10.001 trở lên.max-results
max-results=100
start-index
để truy xuất một tập hợp con các phần tử hoặc dùng riêng phần tử này để hạn chế số lượng phần tử được trả về, bắt đầu bằng phần tử đầu tiên.
Nếu max-results
không được cung cấp, truy vấn sẽ trả về giá trị tối đa mặc định là 1.000 hàng.ga:country
. Vì vậy, khi chỉ phân đoạn theo quốc gia, bạn không thể có quá 300 hàng, ngay cả khi đặt max-results
thành giá trị cao hơn.output
output=dataTable
json
– Xuất thuộc tínhrows
mặc định trong phản hồi có chứa đối tượng JSON.dataTable
– Cho ra một thuộc tínhdataTable
trong phản hồi, chứa đối tượng Bảng dữ liệu. Bạn có thể sử dụng trực tiếp đối tượngData Table
này với hình ảnh trực quan của Google Biểu đồ.
fields
fields=rows,columnHeaders(name,dataType)
Chỉ định các trường sẽ trả về trong một phản hồi một phần. Nếu chỉ sử dụng một tập hợp con các trường trong phản hồi API, thì bạn có thể sử dụng tham số fields
để chỉ định các trường cần đưa vào.
Định dạng của các giá trị tham số yêu cầu của các trường sẽ lỏng lẻo dựa trên cú pháp XPath. Dưới đây là thông tin tóm tắt về cú pháp được hỗ trợ.
- Hãy sử dụng danh sách được phân tách bằng dấu phẩy để chọn nhiều trường.
- Sử dụng
a/b
để chọn trường b được lồng trong trường a; dùnga/b/c
để chọn trường c lồng trong trường b. - Sử dụng bộ chọn phụ để yêu cầu một tập hợp các trường phụ cụ thể của các mảng hoặc đối tượng bằng cách đặt biểu thức trong dấu ngoặc đơn
"( )"
.
Ví dụ:fields=columnHeaders(name,dataType)
chỉ trả về các trườngname
vàdataType
trong mảngcolumnHeaders
. Bạn cũng có thể chỉ định một trường phụ, trong đófields=columnHeader(name)
tương đương vớifields=columnHeader/name
.
prettyPrint
prettyPrint=false
Trả về phản hồi ở định dạng con người có thể đọc được nếu true
.
Giá trị mặc định: false
.
quotaUser
quotaUser=4kh4r2h4
Cho phép bạn thực thi hạn mức trên mỗi người dùng từ ứng dụng phía máy chủ, ngay cả trong trường hợp địa chỉ IP của người dùng không xác định. Điều này có thể xảy ra, chẳng hạn như với các ứng dụng chạy công việc định kỳ trên App Engine thay mặt người dùng. Bạn có thể chọn bất kỳ chuỗi tuỳ ý nào nhận dạng duy nhất một người dùng, nhưng chuỗi này chỉ được có tối đa 40 ký tự.
Thao tác này sẽ ghi đè userIp
nếu bạn cung cấp cả hai.
Phản hồi
Nếu thành công, yêu cầu này sẽ trả về một nội dung phản hồi có cấu trúc JSON được xác định dưới đây. Nếu tham số đầu ra được đặt thành dataTable
, thì yêu cầu sẽ trả về một nội dung phản hồi có cấu trúc JSON (Bảng dữ liệu) được xác định ở bên dưới.
Lưu ý: thuật ngữ "Kết quả" dùng để chỉ toàn bộ tập hợp các hàng khớp với cụm từ tìm kiếm, còn "phản hồi" dùng để chỉ tập hợp các hàng được trả về trên trang kết quả hiện tại. Các giá trị này có thể khác nếu tổng số kết quả lớn hơn kích thước trang cho phản hồi hiện tại, như giải thích trong 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,
...
}
]
}
Trường câu trả lời
Các thuộc tính của cấu trúc nội dung phản hồi được xác định như sau:
Tên thuộc tính | Giá trị | Nội dung mô tả |
---|---|---|
kind |
string |
Loại tài nguyên. Giá trị là "analytics#gaData". |
id |
string |
Mã nhận dạng cho phản hồi dữ liệu này. |
query |
object |
Đối tượng này chứa tất cả các giá trị được truyền dưới dạng tham số đến truy vấn. Ý nghĩa của từng trường được giải thích trong nội dung mô tả về tham số truy vấn tương ứng. |
query.start-date |
string |
Ngày bắt đầu. |
query.end-date |
string |
Ngày kết thúc. |
query.ids |
string |
Mã bảng duy nhất. |
query.dimensions[] |
list |
Danh sách phương diện phân tích. |
query.metrics[] |
list |
Danh sách các chỉ số phân tích. |
query.samplingLevel |
string |
Requested sampling level. |
query.include-empty-rows |
boolean |
Giá trị mặc định là true; nếu bạn đặt thành false, thì các hàng có tất cả giá trị chỉ số bằng 0 sẽ bị loại khỏi phản hồi. |
query.sort[] |
list |
Danh sách các chỉ số hoặc phương diện mà dữ liệu được sắp xếp. |
query.filters |
string |
Danh sách các bộ lọc chỉ số hoặc phương diện được phân tách bằng dấu phẩy. |
query.segment |
string |
Phân đoạn trong Analytics. |
query.start-index |
integer |
Chỉ mục bắt đầu. |
query.max-results |
integer |
Số kết quả tối đa mỗi trang. |
startIndex |
integer |
Chỉ mục bắt đầu của các hàng do tham số truy vấn start-index chỉ định. Giá trị mặc định là 1. |
itemsPerPage |
integer |
Số hàng tối đa mà phản hồi có thể chứa, bất kể số hàng thực tế được trả về. Nếu tham số truy vấn max-results được chỉ định, thì giá trị của itemsPerPage sẽ nhỏ hơn của max-results hoặc 10.000. Giá trị mặc định của itemsPerPage là 1000.
|
totalResults |
integer |
Tổng số hàng trong kết quả truy vấn, bất kể số lượng hàng được trả về trong phản hồi. Đối với những truy vấn dẫn đến một số lượng lớn các hàng, totalResults có thể lớn hơn itemsPerPage .
Xem phần Phân trang để biết thêm thông tin giải thích về totalResults và itemsPerPage đối với các truy vấn lớn.
|
startDate |
string |
Ngày bắt đầu truy vấn dữ liệu, do tham số start-date chỉ định. |
endDate |
string |
Ngày kết thúc cho truy vấn dữ liệu, do tham số end-date chỉ định. |
selfLink |
string |
Liên kết đến trang kết quả này cho truy vấn dữ liệu này. |
previousLink |
string |
Đường liên kết đến trang kết quả trước đó cho truy vấn dữ liệu này. |
nextLink |
string |
Đường liên kết đến trang kết quả tiếp theo cho truy vấn dữ liệu này. |
profileInfo |
object |
Thông tin về chế độ xem (hồ sơ) mà dữ liệu được yêu cầu. Dữ liệu Chế độ xem (Hồ sơ) có sẵn thông qua API Quản lý Google Analytics. |
profileInfo.profileId |
string |
Mã chế độ xem (Hồ sơ), chẳng hạn như 1174 . |
profileInfo.accountId |
string |
Mã tài khoản chứa chế độ xem (hồ sơ) này, chẳng hạn như 30481 . |
profileInfo.webPropertyId |
string |
Mã thuộc tính web chứa chế độ xem (hồ sơ) này, chẳng hạn như UA-30481-1 . |
profileInfo.internalWebPropertyId |
string |
Mã nhận dạng nội bộ của thuộc tính web chứa chế độ xem (hồ sơ) này, chẳng hạn như UA-30481-1 . |
profileInfo.profileName |
string |
Tên của chế độ xem (hồ sơ). |
profileInfo.tableId |
string |
Mã bảng cho chế độ xem (hồ sơ), bao gồm "ga:" theo sau là mã chế độ xem (hồ sơ). |
containsSampledData |
boolean |
Đúng nếu phản hồi chứa dữ liệu được lấy mẫu. |
sampleSize |
string |
Số lượng mẫu dùng để tính toán dữ liệu được lấy mẫu. |
sampleSpace |
string |
Tổng kích thước không gian lấy mẫu. Giá trị này cho biết tổng kích thước không gian mẫu có sẵn mà từ đó các mẫu được chọn. |
columnHeaders[] |
list |
Tiêu đề cột liệt kê tên phương diện, theo sau là tên chỉ số. Thứ tự của các phương diện và chỉ số giống với thứ tự được chỉ định trong yêu cầu thông qua các thông số metrics và dimensions . Số lượng tiêu đề là số lượng
phương diện + số lượng chỉ số. |
columnHeaders[].name |
string |
Tên của phương diện hoặc chỉ số. |
columnHeaders[].columnType |
string |
Loại cột. "PHƯƠNG DIỆN" hoặc "CHỈ SỐ". |
columnHeaders[].dataType |
string |
Kiểu dữ liệu. Các tiêu đề cột phương diện chỉ có
STRING là loại dữ liệu. Tiêu đề cột chỉ số có loại dữ liệu cho các giá trị chỉ số như INTEGER , PERCENT , TIME , CURRENCY , FLOAT , v.v. Hãy xem phản hồi của API siêu dữ liệu để biết mọi loại dữ liệu có thể có.
|
totalsForAllResults |
object |
Tổng giá trị cho các chỉ số được yêu cầu dưới dạng cặp khoá-giá trị của tên và giá trị chỉ số. Thứ tự của các giá trị tổng của chỉ số giống với thứ tự của các chỉ số được chỉ định trong yêu cầu. |
rows[] |
list |
Các hàng dữ liệu Analytics, trong đó mỗi hàng chứa một danh sách các giá trị phương diện, theo sau là các giá trị chỉ số. Thứ tự của các phương diện và chỉ số cũng giống như thứ tự được chỉ định trong yêu cầu. Mỗi hàng có một danh sách gồm N trường, trong đó N = số phương diện + số lượng chỉ số. |
{
"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,
...
}
]
}
Trường câu trả lời
Các thuộc tính của cấu trúc nội dung phản hồi được xác định như sau:
Tên thuộc tính | Giá trị | Nội dung mô tả |
---|---|---|
kind |
string |
Loại tài nguyên. Giá trị là "analytics#gaData". |
id |
string |
Mã nhận dạng cho phản hồi dữ liệu này. |
query |
object |
Đối tượng này chứa tất cả các giá trị được truyền dưới dạng tham số đến truy vấn. Ý nghĩa của từng trường được giải thích trong nội dung mô tả về tham số truy vấn tương ứng. |
query.start-date |
string |
Ngày bắt đầu. |
query.end-date |
string |
Ngày kết thúc. |
query.ids |
string |
Mã bảng duy nhất. |
query.dimensions[] |
list |
Danh sách phương diện phân tích. |
query.metrics[] |
list |
Danh sách các chỉ số phân tích. |
query.samplingLevel |
string |
Requested sampling level. |
query.include-empty-rows |
boolean |
Giá trị mặc định là true; nếu bạn đặt thành false, thì các hàng có tất cả giá trị chỉ số bằng 0 sẽ bị loại khỏi phản hồi. |
query.sort[] |
list |
Danh sách các chỉ số hoặc phương diện mà dữ liệu được sắp xếp. |
query.filters |
string |
Danh sách các bộ lọc chỉ số hoặc phương diện được phân tách bằng dấu phẩy. |
query.segment |
string |
Phân đoạn trong Analytics. |
query.start-index |
integer |
Chỉ mục bắt đầu. |
query.max-results |
integer |
Số kết quả tối đa mỗi trang. |
startIndex |
integer |
Chỉ mục bắt đầu của các hàng do tham số truy vấn start-index chỉ định. Giá trị mặc định là 1. |
itemsPerPage |
integer |
Số hàng tối đa mà phản hồi có thể chứa, bất kể số hàng thực tế được trả về. Nếu tham số truy vấn max-results được chỉ định, thì giá trị của itemsPerPage sẽ nhỏ hơn của max-results hoặc 10.000. Giá trị mặc định của itemsPerPage là 1000.
|
totalResults |
integer |
Tổng số hàng trong kết quả truy vấn, bất kể số lượng hàng được trả về trong phản hồi. Đối với những truy vấn dẫn đến một số lượng lớn các hàng, totalResults có thể lớn hơn itemsPerPage .
Xem phần Phân trang để biết thêm thông tin giải thích về totalResults và itemsPerPage đối với các truy vấn lớn.
|
startDate |
string |
Ngày bắt đầu truy vấn dữ liệu, do tham số start-date chỉ định. |
endDate |
string |
Ngày kết thúc cho truy vấn dữ liệu, do tham số end-date chỉ định. |
selfLink |
string |
Liên kết đến trang kết quả này cho truy vấn dữ liệu này. |
previousLink |
string |
Đường liên kết đến trang kết quả trước đó cho truy vấn dữ liệu này. |
nextLink |
string |
Đường liên kết đến trang kết quả tiếp theo cho truy vấn dữ liệu này. |
profileInfo |
object |
Thông tin về chế độ xem (hồ sơ) mà dữ liệu được yêu cầu. Dữ liệu Chế độ xem (Hồ sơ) có sẵn thông qua API Quản lý Google Analytics. |
profileInfo.profileId |
string |
Mã chế độ xem (Hồ sơ), chẳng hạn như 1174 . |
profileInfo.accountId |
string |
Mã tài khoản chứa chế độ xem (hồ sơ) này, chẳng hạn như 30481 . |
profileInfo.webPropertyId |
string |
Mã thuộc tính web chứa chế độ xem (hồ sơ) này, chẳng hạn như UA-30481-1 . |
profileInfo.internalWebPropertyId |
string |
Mã nhận dạng nội bộ của thuộc tính web chứa chế độ xem (hồ sơ) này, chẳng hạn như UA-30481-1 . |
profileInfo.profileName |
string |
Tên của chế độ xem (hồ sơ). |
profileInfo.tableId |
string |
Mã bảng cho chế độ xem (hồ sơ), bao gồm "ga:" theo sau là mã chế độ xem (hồ sơ). |
containsSampledData |
boolean |
Đúng nếu phản hồi chứa dữ liệu được lấy mẫu. |
sampleSize |
string |
Số lượng mẫu dùng để tính toán dữ liệu được lấy mẫu. |
sampleSpace |
string |
Tổng kích thước không gian lấy mẫu. Giá trị này cho biết tổng kích thước không gian mẫu có sẵn mà từ đó các mẫu được chọn. |
columnHeaders[] |
list |
Tiêu đề cột liệt kê tên phương diện, theo sau là tên chỉ số. Thứ tự của các phương diện và chỉ số giống với thứ tự được chỉ định trong yêu cầu thông qua các thông số metrics và dimensions . Số lượng tiêu đề là số lượng
phương diện + số lượng chỉ số. |
columnHeaders[].name |
string |
Tên của phương diện hoặc chỉ số. |
columnHeaders[].columnType |
string |
Loại cột. "PHƯƠNG DIỆN" hoặc "CHỈ SỐ". |
columnHeaders[].dataType |
string |
Kiểu dữ liệu. Các tiêu đề cột phương diện chỉ có
STRING là loại dữ liệu. Tiêu đề cột chỉ số có loại dữ liệu cho các giá trị chỉ số như INTEGER , PERCENT , TIME , CURRENCY , FLOAT , v.v. Hãy xem phản hồi của API siêu dữ liệu để biết mọi loại dữ liệu có thể có.
|
totalsForAllResults |
object |
Tổng giá trị cho các chỉ số được yêu cầu dưới dạng cặp khoá-giá trị của tên và giá trị chỉ số. Thứ tự của các giá trị tổng của chỉ số giống với thứ tự của các chỉ số được chỉ định trong yêu cầu. |
dataTable |
object |
Đối tượng Bảng dữ liệu có thể dùng với Google Biểu đồ. |
dataTable.cols[] |
list |
Danh sách mã mô tả cột cho phương diện đứng trước chỉ số. Thứ tự của các phương diện và chỉ số giống với thứ tự được chỉ định trong yêu cầu thông qua các thông số metrics và dimensions . Số lượng cột là số lượng phương diện +
số lượng chỉ số. |
dataTable.cols[].id |
string |
Mã nhận dạng, có thể dùng để tham chiếu đến một cột cụ thể (như một giải pháp thay thế cho việc sử dụng chỉ mục cột). Mã phương diện hoặc chỉ số được dùng để đặt giá trị này. |
dataTable.cols[].label |
string |
Nhãn cho cột (có thể hiển thị bằng hình ảnh trực quan). Mã phương diện hoặc chỉ số được dùng để đặt giá trị này. |
dataTable.cols[].type |
string |
Loại dữ liệu cho cột này. |
dataTable.rows[] |
list |
Các hàng dữ liệu Analytics ở định dạng Bảng dữ liệu, trong đó mỗi hàng là một đối tượng chứa danh sách giá trị ô cho các phương diện đứng trước các chỉ số. Thứ tự của các phương diện và chỉ số cũng giống như thứ tự được chỉ định trong yêu cầu. Mỗi ô có một danh sách gồm N trường, trong đó N = số phương diện + số chỉ số. |
Mã lỗi
API Báo cáo chính sẽ trả về mã trạng thái HTTP 200
nếu yêu cầu thành công. Nếu có lỗi xảy ra trong quá trình xử lý truy vấn, API sẽ trả về mã lỗi và nội dung mô tả.
Mỗi ứng dụng sử dụng API phân tích đều cần triển khai logic xử lý lỗi thích hợp. Để biết thông tin chi tiết về mã lỗi và cách xử lý, hãy đọc
Hướng dẫn tham khảo về Phản hồi lỗi.
Thử ngay!
Bạn có thể thử các truy vấn đến API báo cáo chính.
-
Để xem các tổ hợp chỉ số và phương diện hợp lệ trong một truy vấn, hãy nhập giá trị mẫu cho các thông số trong Trình khám phá truy vấn. Kết quả của truy vấn mẫu được hiển thị dưới dạng bảng chứa các giá trị cho tất cả các chỉ số và phương diện được chỉ định.
-
Để đưa ra yêu cầu về dữ liệu trực tiếp và xem phản hồi ở định dạng JSON, hãy thử phương thức
analytics.data.ga.get
trong Trình khám phá API dữ liệu của Google.
Lấy mẫu
Google Analytics sẽ nhanh chóng tính toán một số kiểu kết hợp phương diện và chỉ số nhất định. Để trả về dữ liệu trong một thời gian hợp lý, Google Analytics có thể chỉ xử lý một mẫu dữ liệu.
Bạn có thể chỉ định cấp độ lấy mẫu để sử dụng cho một yêu cầu bằng cách đặt tham số samplingLevel.
Nếu phản hồi của API Báo cáo chính chứa dữ liệu được lấy mẫu, thì trường phản hồi containsSampledData
sẽ là true
.
Ngoài ra, 2 thuộc tính sẽ cung cấp thông tin về cấp độ lấy mẫu cho truy vấn: sampleSize
và sampleSpace
.
Với 2 giá trị này, bạn có thể tính toán tỷ lệ phần trăm số phiên được dùng cho truy vấn. Ví dụ: nếu sampleSize
là 201,000
và sampleSpace
là 220,000
thì báo cáo sẽ dựa trên (201.000 / 220.000) * 100 = 91,36% số phiên.
Vui lòng xem phần Lấy mẫu để biết nội dung mô tả chung về hoạt động lấy mẫu và cách sử dụng phương pháp lấy mẫu trong Google Analytics.
Xử lý kết quả dữ liệu lớn
Nếu bạn muốn truy vấn của mình trả về một tập hợp kết quả lớn, hãy sử dụng các nguyên tắc dưới đây để giúp bạn tối ưu hoá truy vấn API, tránh lỗi và giảm thiểu việc vượt quá hạn mức. Xin lưu ý rằng chúng tôi thiết lập một đường cơ sở về hiệu suất bằng cách cho phép tối đa 7 phương diện và 10 chỉ số trong một yêu cầu API bất kỳ. Mặc dù một số truy vấn chỉ định số lượng lớn chỉ số và phương diện có thể mất nhiều thời gian xử lý hơn so với các truy vấn khác, nhưng việc giới hạn số lượng chỉ số được yêu cầu có thể là không đủ để cải thiện hiệu suất truy vấn. Thay vào đó, bạn có thể sử dụng các kỹ thuật sau để có kết quả hiệu suất tốt nhất.
Giảm phương diện cho mỗi truy vấn
API cho phép chỉ định tối đa 7 phương diện trong một yêu cầu bất kỳ. Nhiều lần, Google Analytics phải nhanh chóng tính toán kết quả của những truy vấn phức tạp này. Việc này có thể đặc biệt tốn thời gian nếu số lượng hàng thu được quá lớn. Ví dụ: việc truy vấn từ khoá theo thành phố theo giờ có thể khớp với hàng triệu hàng dữ liệu. Bạn có thể cải thiện hiệu suất bằng cách giảm số lượng hàng mà Google Analytics cần xử lý bằng cách giới hạn số lượng phương diện trong truy vấn của bạn.
Tách truy vấn theo Phạm vi ngày
Thay vì phân trang theo kết quả theo ngày tháng của một phạm vi ngày dài, hãy cân nhắc tạo các truy vấn riêng trong một tuần – hoặc thậm chí một ngày – mỗi lần. Tất nhiên, đối với một tập dữ liệu lớn, ngay cả một yêu cầu dữ liệu trong một ngày cũng có thể trả về nhiều hơn max-results
, trong trường hợp đó là không thể tránh được việc phân trang. Tuy nhiên, trong mọi trường hợp, nếu số hàng phù hợp với truy vấn của bạn nhiều hơn max-results
, thì việc chia nhỏ phạm vi ngày có thể làm giảm tổng thời gian truy xuất kết quả. Phương pháp này có thể cải thiện hiệu suất trong cả truy vấn đơn luồng và truy vấn song song.
Paging
Việc phân trang kết quả có thể là một cách hữu ích để chia các tập hợp kết quả lớn thành các phần có thể quản lý. Trường totalResults
cho biết có bao nhiêu hàng phù hợp, còn itemsPerPage
cho biết số hàng tối đa có thể trả về trong kết quả.
Nếu tỷ lệ totalResults
so với itemsPerPage
ở mức cao, thì các truy vấn riêng lẻ có thể mất nhiều thời gian hơn mức cần thiết. Nếu chỉ cần một số lượng hàng hạn chế, chẳng hạn như cho mục đích hiển thị, bạn có thể đặt giới hạn rõ ràng về kích thước phản hồi thông qua tham số max-results
. Tuy nhiên, nếu ứng dụng của bạn cần xử lý toàn bộ một tập hợp lớn kết quả, thì việc yêu cầu số hàng tối đa được phép có thể hiệu quả hơn.
Sử dụng gzip
Một cách dễ dàng và thuận tiện để giảm băng thông cần thiết cho mỗi yêu cầu là bật tính năng nén gzip. Mặc dù việc này yêu cầu thêm thời gian của CPU để giải nén kết quả, nhưng việc đánh đổi chi phí mạng thường rất đáng để thực hiện. Để nhận được phản hồi được mã hoá bằng gzip, bạn phải làm hai việc: Đặt tiêu đề Accept-Encoding
và sửa đổi tác nhân người dùng để chứa chuỗi gzip
.
Dưới đây là ví dụ về các tiêu đề HTTP được định dạng đúng cách để bật chức năng nén gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)