API báo cáo chính – Hướng dẫn tham khảo

Tài liệu này cung cấp tài liệu tham khảo hoàn chỉnh cho cả truy vấn và phản hồi của 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 yêu cầu một mã chế độ xem (hồ sơ), ngày bắt đầu và ngày kết thúc và ít nhất một chỉ số. Bạn cũng có thể cung cấp thêm các tham số truy vấn như phương diện, bộ lọc và phân đoạn để tinh chỉnh truy vấn của mình. Hãy xem Hướng dẫn tổng quan để hiểu cách thức tất cả các khái niệm này hoạt động cùng nhau.

Yêu cầu

API này 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 từng 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 đầy đủ:

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 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. Hãy nhấp vào từng tên 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 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 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 YYYY-MM-DD hoặc dưới dạng ngày tương đối (ví dụ: today, yesterday hoặc NdaysAgo, trong đó N là số nguyên dương).
end-date string 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 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 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:
  • DEFAULT – Trả về phản hồi với 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 quy mô mẫu nhỏ hơn.
  • HIGHER_PRECISION – Trả về một phản hồi chính xác hơn bằng cách sử dụng một kích thước mẫu lớn, nhưng điều này có thể khiến phản hồi chậm hơn.
include-empty-rows boolean no 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.
start-index integer no Hàng dữ liệu đầu tiên cần truy xuất, bắt đầu từ 1. Sử dụng thông số này làm cơ chế phân trang cùng với thông số max-results.
max-results integer no Số hàng tối đa cần đư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. Giá trị được chấp nhận là jsondataTable. 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 mà lệnh gọi API đang được thực hiện. 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 hàm callback JavaScript xử lý phản hồi. Dùng trong yêu cầu JSON-P liên quan đến JavaScript.
key string no Dùng cho lệnh uỷ quyền OAuth 1.0a để chỉ định ứng dụng của bạn nhận hạn mức. Ví dụ: key=AldefliuhSFADSfasdfasdfASdf.

Chi tiết tham số truy vấn

ids

ids=ga:12345
Bắt buộc.
Mã nhận dạng duy nhất dùng để truy xuất dữ liệu của Analytics. Mã nhận dạng này là sự nối giữa không gian tên 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
Bắt buộc.
Mọi yêu cầu về dữ liệu trong Analytics phải chỉ định phạm vi ngày. Nếu bạn không đưa các tham số start-dateend-date vào yêu cầu, thì máy chủ sẽ trả về một lỗi. Bạn có thể sử dụng mẫu YYYY-MM-DD hoặc mẫu tương đối cho một ngày cụ thể bằng mẫu 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.
Ngày tương đối luôn tương ứng với ngày hiện tại tại thời điểm truy vấn và dựa trên múi giờ của chế độ xem (hồ sơ) được chỉ định trong truy vấn.

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
Bắt buộc.
Mọi yêu cầu về dữ liệu trong Analytics phải chỉ định phạm vi ngày. Nếu bạn không đưa các tham số start-dateend-date vào yêu cầu, thì máy chủ sẽ trả về một lỗi. Bạn có thể sử dụng mẫu YYYY-MM-DD hoặc mẫu tương đối cho một ngày cụ thể bằng mẫu 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 trên đối với end-date.
Ngày tương đối luôn tương ứng với ngày hiện tại tại thời điểm truy vấn và dựa trên múi giờ của chế độ xem (hồ sơ) được chỉ định trong truy vấn.

Ví dụ về phạm vi ngày trong 10 ngày qua (kể 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
Không bắt buộc.
Thông số 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ù 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 yêu cầu cung cấp 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 từ 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 ý những 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 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ố.
  • Chỉ có một số phương diện nhất định có thể được truy vấn 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 nào có thể được sử dụng cùng nhau.


metrics

metrics=ga:sessions,ga:bounces
Bắt buộc.
Số liệu thống kê tổng hợp về hoạt động của người dùng trên trang web của bạn, chẳng hạn như số lượt nhấp hoặc lượt xem trang. Nếu một truy vấn không có tham số dimensions, thì các 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ụ: ga:pageviews được yêu cầu 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 ý những điều sau:
  • Bất kỳ yêu cầu nào cũng phải cung cấp ít nhất một chỉ số; một yêu cầu không được chỉ gồm 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ố từ nhiều danh mục cùng nhau, miễn là bạn không chỉ định phương diện nào.
  • 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ó sự 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ông tin chi tiết.


sắp xếp

sort=ga:country,ga:browser
Không bắt buộc.

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 xác đị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 quyết câu hỏi "Các quốc gia hàng đầu của tôi là những quốc gia nào và họ sử dụng những trình duyệt nào nhiều nhất?" bạn có thể tạo truy vấn với tham số sau. Trình phân tích cú pháp này sẽ sắp xếp trước theo ga:country rồi sau đó theo 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à gì và quốc gia nào sử dụng trình duyệt đó nhiều nhất?", bạn có thể tạo một truy vấn bằng tham số sau. Trình phân tích cú pháp này sẽ sắp xếp trước tiên theo ga:browser rồi sau đó theo 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ặc metrics. 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 theo 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.
  • Ngày được sắp xếp theo thứ tự tăng dần theo ngày theo mặc định.

bộ lọc

filters=ga:medium%3D%3Dreferral
Không bắt buộc.

Tham số chuỗi truy vấn filters hạn chế dữ liệu được trả về từ yêu cầu của bạn. Để sử dụng thông số filters, hãy cung cấp một 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êu cầu ga:pageviewsga: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ẽ giới hạn các dò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 so với 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ử 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 những phương diện có liên quan. Trong ví dụ trên, số lượt xem trang sẽ chỉ là những lượt xem trang khi Firefox là trình duyệt.
  • Lọc chỉ số: Quá trình lọc 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 cụm từ tìm kiếm của bạn, miễn là tất cả các phương diện/chỉ số trong yêu cầu bộ lọc đều là những kiểu kết hợp hợp lệ. Ví dụ: bạn có thể muốn truy vấn danh sách lượt xem trang có 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 này:

  • 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 kiểu khớp bộ lọc sẽ sử dụng. Toán tử dành riêng cho thứ nguyên hoặc chỉ số.
  • biểu thức — cho biết các giá trị cần có trong 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ử bộ lọc cho phương diện và 6 toán tử bộ lọc cho chỉ số. Các toán tử phải được mã hoá URL thì mới có thể đư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ế những bộ lọc cần mã hoá URL, vì Trình khám phá truy vấn sẽ tự động mã hoá URL có chứa chuỗi và dấu cách.

Bộ lọc chỉ số
Đơn vị tổ chức Nội dung mô tả Biểu mẫu được mã hóa URL Ví dụ
== Bằng %3D%3D Trả về 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ề kết quả có 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ề kết quả có thời gian trên trang hoàn toàn lớn hơn 10 giây:
filters=ga:timeOnPage%3E10
< Nhỏ hơn %3C Trả về kết quả có thời lượng 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ề 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ề kết quả trong đó thời gian trên trang từ 10 giây trở xuống:
filters=ga:timeOnPage%3C%3D10

Bộ lọc phương diện
Đơn vị tổ chức Nội dung mô tả Biểu mẫu được mã hóa URL Ví dụ:
== Khớp chính xác %3D%3D Các chỉ số tổng hợp theo đó thành phố là Irvine:
filters=ga:city%3D%3DIrvine
!= Không khớp !%3D Những chỉ số tổng hợp mà thành phố không phảiIrvine:
filters=ga:city!%3DIrvine
=@ Chứa chuỗi con %3D@ Các chỉ số tổng hợp trong đó 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 mà thành phố không chứa York:
filters=ga:city!@York
=~ Chứa kết quả phù hợp cho biểu thức chính quy %3D~ Các chỉ số tổng hợp có thành phố bắt đầu bằng Mới:
filters=ga:city%3D~%5ENew.*
(%5E là URL được mã hoá từ ký tự ^ gắn một mẫu vào đầ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 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 và 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 \,
  • Biểu thức chính quy – Bạn cũng có thể dùng biểu thức chính quy trong biểu thức lọc bằng toán tử =~!~. Cú pháp của các biểu thức chính quy này 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 được 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.

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 ORAND. Điều 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ả.

HOẶC

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 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 URL đều 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 trên hệ điều hành (Windows HOẶC Macintosh):
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

Toán tử AND được xác định bằng dấu chấm phẩy (;). Sau toán tử OR, bạn có thể dùng CAN để 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 URL đều 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 OR Macintosh) VÀ trình duyệt là (Firefox OR 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
Không bắt buộc.

Để biết thông tin chi tiết đầy đủ về cách yêu cầu phân đoạn trong API báo cáo chính, hãy xem Hướng dẫn về phân đoạn cho nhà phát triển.

Để biết thông tin tổng quan về khái niệm của phân đoạn, hãy xem Tài liệu tham khảo về tính năng của phân đoạn Phân đoạn trong Trung tâm trợ giúp.

Phương diện và chỉ số được phép trong phân khúc.
Không phải phương diện và chỉ số nào cũng có thể dùng được trong phân khúc. Để xem xét những phương diện và chỉ số được phép trong phân đoạn, hãy truy cập vào Trình khám phá phương diện và chỉ số.


samplingLevel

samplingLevel=DEFAULT
Không bắt buộc.
Dùng tham số này để đặt mức lấy mẫu (tức là số phiên được dùng để tính toán kết quả) cho một truy vấn báo cáo. Các giá trị được phép là nhất quán với giao diện web và bao gồm:
  • DEFAULT – Trả về phản hồi với 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 quy mô mẫu nhỏ hơn.
  • HIGHER_PRECISION – Trả về một phản hồi chính xác hơn bằng cách sử dụng một kích thước mẫu lớn, nhưng điều này có thể khiến phản hồi chậm hơn.
Nếu không được cung cấp, hệ thống sẽ sử dụng cấp lấy mẫu DEFAULT.
Xem phần Lấy mẫu để biết thông tin chi tiết về cách tính tỷ lệ phần trăm số phiên được dùng cho một truy vấn.

bao gồm hàng rỗng

include-empty-rows=true
Không bắt buộc.
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. Ví dụ: nếu bạn đưa nhiều chỉ số vào một truy vấn, các hàng chỉ bị xoá nếu tất cả giá trị của chỉ số đó bằng 0. Điều này có thể hữu ích khi đưa ra yêu cầu mà trong đó số lượng hàng hợp lệ dự kiến sẽ nhỏ hơn nhiều so với số lượng giá trị phương diện dự kiến.

start-index

start-index=10
Không bắt buộc.
Nếu không được cung cấp, chỉ mục bắt đầu sẽ là 1. (Chỉ mục kết quả là dựa trên 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 thông số này làm cơ chế phân trang cùng với thông số max-results trong các trường hợp khi 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ừ 10.001 trở lên.

max-results

max-results=100
Không bắt buộc.
Số hàng tối đa có thể đưa vào câu trả lời này. Bạn có thể sử dụng thuộc tính này kết hợp với start-index để truy xuất một tập hợp con các phần tử hoặc sử dụng riêng phần tử này để hạn chế số lượng phần tử được trả về, bắt đầu từ 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.
API báo cáo chính của Analytics sẽ trả về tối đa 10.000 hàng cho mỗi yêu cầu, bất kể số lượng hàng mà bạn yêu cầu. Thuộc tính này cũng có thể trả về ít hàng hơn so với yêu cầu nếu không có nhiều phân khúc phương diện như bạn mong đợi. Ví dụ: có thể có ít hơn 300 giá trị cho ga:country, vì vậy khi chỉ phân đoạn theo quốc gia, bạn không thể nhận được hơn 300 hàng, ngay cả khi bạn đặt max-results thành giá trị cao hơn.

output

output=dataTable
Không bắt buộc.
Dùng tham số này để đặt loại đầu ra của dữ liệu Analytics được trả về trong phản hồi. Sau đây là các giá trị được phép:
  • json – Xuất ra thuộc tính rows mặc định trong phản hồi, chứa đối tượng JSON.
  • dataTable – Tạo ra một thuộc tính dataTable 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ượng Data Table này với hình ảnh trực quan của Google Biểu đồ.
Nếu không được cung cấp, phản hồi JSON mặc định sẽ được sử dụng.

fields

fields=rows,columnHeaders(name,dataType)
Không bắt buộc.

Chỉ định các trường cần trả về trong phản hồi một phần. Nếu chỉ sử dụng một số trường trong phản hồi API, bạn có thể dùng tham số fields để chỉ định những trường cần đưa vào.

Định dạng của các trường yêu cầu giá trị tham số thường dựa trên cú pháp XPath. Dưới đây là tóm tắt cú pháp được hỗ trợ.

  • Sử dụng danh sách được phân tách bằng dấu phẩy để chọn nhiều trường.
  • Dùng a/b để chọn trường b được lồng trong trường a; dùng a/b/c để chọn trường c lồng trong trường b.
  • Sử dụng trình chọn phụ để yêu cầu một tập hợp các trường phụ cụ thể của 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ường namedataType trong mảng columnHeaders. Bạn cũng có thể chỉ định một trường phụ, trong đó fields=columnHeader(name) tương đương với fields=columnHeader/name.

prettyPrint

prettyPrint=false
Không bắt buộc.

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
Không bắt buộc.

Cho phép bạn thực thi hạn mức cho mỗi người dùng từ mộ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 cron job 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 giúp nhận dạng riêng một người dùng. Tuy nhiên, 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 bên dưới. 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 hàng khớp với cụm từ tìm kiếm, trong khi "phản hồi" là 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.

JSON
{
  "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,
      ...
    }
  ]
}

Các 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 phần mô tả của 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 trong Analytics.
query.metrics[] list Danh sách các chỉ số trong Analytics.
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ị bỏ qua trong 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 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 khúc Analytics.
query.start-index integer Chỉ mục bắt đầu.
query.max-results integer Số kết quả tối đa trên 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ẽ là giá trị 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 các truy vấn dẫn đến một số lượng lớn hàng, totalResults có thể lớn hơn itemsPerPage. Hãy xem phần Phân trang để biết thêm nội dung giải thích về totalResultsitemsPerPage đối với các truy vấn lớn.
startDate string Ngày bắt đầu truy vấn dữ liệu, như được chỉ định bằng tham số start-date.
endDate string Ngày kết thúc cho truy vấn dữ liệu, như được chỉ định bằng tham số end-date.
profileInfo object Thông tin về chế độ xem (hồ sơ) mà dữ liệu được yêu cầu. Dữ liệu về 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 ID nội bộ cho 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 nội dung phản hồi chứa dữ liệu được lấy mẫu.
sampleSize string Số lượng mẫu được 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à 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ố metricsdimensions. Số lượng tiêu đề bằng 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. "DIMENSION" hoặc "METRIC".
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. Các tiêu đề cột chỉ số có các loại dữ liệu cho các giá trị chỉ số, chẳng hạn 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 tất cả các 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 như thứ tự của 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ố giống như được chỉ định trong yêu cầu. Mỗi hàng có một danh sách N trường, trong đó N = số lượng phương diện + số lượng chỉ số.
JSON (Bảng dữ liệu)
{
  "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,
      ...
    }
  ]
}

Các 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 phần mô tả của 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 trong Analytics.
query.metrics[] list Danh sách các chỉ số trong Analytics.
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ị bỏ qua trong 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 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 khúc Analytics.
query.start-index integer Chỉ mục bắt đầu.
query.max-results integer Số kết quả tối đa trên 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ẽ là giá trị 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 các truy vấn dẫn đến một số lượng lớn hàng, totalResults có thể lớn hơn itemsPerPage. Hãy xem phần Phân trang để biết thêm nội dung giải thích về totalResultsitemsPerPage đối với các truy vấn lớn.
startDate string Ngày bắt đầu truy vấn dữ liệu, như được chỉ định bằng tham số start-date.
endDate string Ngày kết thúc cho truy vấn dữ liệu, như được chỉ định bằng tham số end-date.
profileInfo object Thông tin về chế độ xem (hồ sơ) mà dữ liệu được yêu cầu. Dữ liệu về 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 ID nội bộ cho 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 nội dung phản hồi chứa dữ liệu được lấy mẫu.
sampleSize string Số lượng mẫu được 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à 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ố metricsdimensions. Số lượng tiêu đề bằng 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. "DIMENSION" hoặc "METRIC".
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. Các tiêu đề cột chỉ số có các loại dữ liệu cho các giá trị chỉ số, chẳng hạn 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 tất cả các 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 như thứ tự của chỉ số được chỉ định trong yêu cầu.
dataTable object Đối tượng Bảng dữ liệu có thể được sử dụng với Google Biểu đồ.
dataTable.cols[] list Danh sách các chỉ số mô tả cột cho các phương diện, theo sau là chỉ số. Thứ tự của các phương diện và chỉ số giống như thứ tự được chỉ định trong yêu cầu thông qua các thông số metricsdimensions. Số lượng cột là số lượng phương diện + số lượng chỉ số.
dataTable.cols[].id string Một 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ể được 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 Kiểu 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 theo sau là các chỉ số. Thứ tự của các phương diện và chỉ số giống như được chỉ định trong yêu cầu. Mỗi ô có danh sách N trường, trong đó N = số phương diện + số lượng 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 xảy ra lỗi trong quá trình xử lý một truy vấn, thì API sẽ trả về một 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.

Hãy thử ngay!

Bạn có thể dùng thử các truy vấn đối với 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 tham 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 với 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.

Hoạt động lấy mẫu

Google Analytics sẽ nhanh chóng tính toán một số tổ hợp phương diện và chỉ số nhất định. Để trả về dữ liệu trong một khoảng 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: sampleSizesampleSpace. Với 2 giá trị này, bạn có thể tính tỷ lệ phần trăm số phiên được sử dụng cho truy vấn. Ví dụ: nếu sampleSize201,000sampleSpace220,000, thì báo cáo sẽ dựa trên (201.000 / 220.000) * 100 = 91,36% số phiên.

Hãy xem phần Lấy mẫu để biết nội dung mô tả chung về việc lấy mẫu và cách lấy mẫu được sử dụng 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ả có kích thước lớn, hãy làm theo các nguyên tắc dưới đây để tối ưu hoá truy vấn API, tránh lỗi và giảm thiểu hạn mức. Xin lưu ý rằng chúng tôi thiết lập đườ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ể 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 bất kỳ yêu cầu nào. Nhiều lần, Google Analytics phải tính toán nhanh 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 có nhiều hàng. 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ố 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 thông qua các kết quả nhập theo ngày trong một phạm vi ngày dài, hãy cân nhắc tạo các truy vấn riêng biệt mỗi tuần hoặc thậm chí một ngày. Tất nhiên, đối với một tập dữ liệu lớn, ngay cả yêu cầu dữ liệu của một ngày cũng có thể trả về nhiều hơn max-results. Trong trường hợp này, việc phân trang không thể tránh được. Tuy nhiên, trong mọi trường hợp, nếu số lượng hàng phù hợp của truy vấn nhiều hơn max-results, thì việc tách riêng 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 cho cả truy vấn đơn luồng và truy vấn song song.

Paging

Việc phân trang thông qua kết quả có thể là một cách hữu ích để chia các nhóm 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 trùng khớp, còn itemsPerPage cho số hàng tối đa có thể trả về trong kết quả. Nếu tỷ lệ totalResults trên itemsPerPage cao, thì các truy vấn riêng lẻ có thể sẽ mất nhiều thời gian hơn mức cần thiết. Nếu chỉ cần một số hàng hạn chế, chẳng hạn như cho mục đích hiển thị, bạn có thể thấy thuận tiện khi đặ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 chức năng nén gzip. Mặc dù phương thứ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 với chi phí mạng thường rất đáng giá. Để 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)