Tài liệu này giải thích các khái niệm quan trọng về cách sử dụng API siêu dữ liệu để truy cập vào danh sách và thuộc tính của các cột Google Analytics.
Giới thiệu
API siêu dữ liệu trả về danh sách các cột (tức là phương diện và chỉ số) hiển thị trong API báo cáo của Google Analytics và thuộc tính của các cột đó. Nếu bạn mới sử dụng API này, hãy đọc bài viết Tổng quan về API siêu dữ liệu để biết thêm thông tin về API siêu dữ liệu.
Trước khi bắt đầu
Tất cả API Google Analytics đều được truy cập theo cách tương tự. Trước khi bắt đầu sử dụng API siêu dữ liệu, bạn nên:
- Hãy đọc trang thư viện ứng dụng để biết danh sách đầy đủ các thư viện ứng dụng cụ thể của ngôn ngữ lập trình hoạt động với API.
- Đọc Hướng dẫn tham khảo để tìm hiểu về giao diện API và cách truy cập vào dữ liệu mà không cần thư viện ứng dụng.
Mỗi thư viện ứng dụng cung cấp một đối tượng dịch vụ phân tích duy nhất để truy cập vào tất cả dữ liệu API siêu dữ liệu. Để tạo đối tượng dịch vụ dùng với API siêu dữ liệu, bạn thường phải thực hiện các bước sau:
- Đăng ký ứng dụng của bạn trong Google API Console.
- Tạo một đối tượng dịch vụ Analytics và đặt Khoá API.
Đăng ký và khoá API
Ứng dụng của bạn cần tự xác định mỗi khi gửi yêu cầu đến API Analytics, bằng cách thêm khoá API vào mỗi yêu cầu.
Nhận và sử dụng khoá API
Cách lấy khoá API:
- Mở trang Thông tin xác thực trong Bảng điều khiển API.
-
API này hỗ trợ 2 loại thông tin đăng nhập.
Tạo bất kỳ thông tin đăng nhập nào phù hợp với dự án của bạn:
-
OAuth 2.0: Bất cứ khi nào ứng dụng yêu cầu dữ liệu riêng tư của người dùng, ứng dụng phải gửi mã thông báo OAuth 2.0 kèm theo yêu cầu. Trước tiên, ứng dụng sẽ gửi một mã ứng dụng khách và có thể là mật khẩu ứng dụng khách để lấy một mã thông báo. Bạn có thể tạo thông tin đăng nhập OAuth 2.0 cho các ứng dụng web, tài khoản dịch vụ hoặc ứng dụng đã cài đặt.
Lưu ý: Vì API này không có bất kỳ phương thức nào yêu cầu phải uỷ quyền OAuth 2.0, nên bạn có thể chỉ cần lấy khoá API được mô tả dưới đây. Tuy nhiên, nếu ứng dụng của bạn gọi các API khác yêu cầu người dùng cho phép, thì bạn vẫn cần có thông tin đăng nhập OAuth 2.0.
Để biết thêm thông tin, hãy xem tài liệu về OAuth 2.0.
-
Khoá API: Yêu cầu không cung cấp mã thông báo OAuth 2.0 phải gửi khoá API. Khoá này giúp xác định dự án của bạn và cung cấp quyền truy cập API, hạn mức và báo cáo.
API hỗ trợ một số loại hạn chế đối với khoá API. Nếu khoá API mà bạn cần chưa tồn tại, hãy tạo một khoá API trong Console bằng cách nhấp vào Tạo thông tin đăng nhập > Khoá API. Bạn có thể hạn chế khoá trước khi sử dụng trong phiên bản phát hành công khai bằng cách nhấp vào Restrict key (Hạn chế khoá) rồi chọn một trong các Restrict (Hạn chế).
-
Để giữ an toàn cho khoá API, hãy làm theo các phương pháp hay nhất để sử dụng khoá API một cách an toàn.
Sau khi bạn có khoá API, ứng dụng của bạn có thể thêm tham số truy vấn key=yourAPIKey vào tất cả các URL yêu cầu.
Khoá API an toàn để nhúng trong URL; không cần phương thức mã hoá.
Các đoạn mã sau đây minh hoạ cách đặt Khoá API cho các thư viện ứng dụng khác nhau:
Java
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.services.analytics.Analytics;
import com.google.api.services.analytics.AnalyticsRequestInitializer;
public class ApiKeySample {
private static final String API_KEY = "YOUR API KEY";
public static void main(String[] args) {
NetHttpTransport netHttpTransport = new NetHttpTransport();
JacksonFactory jacksonFactory = new JacksonFactory();
// Set the API Key
AnalyticsRequestInitializer analyticsInitializer = new AnalyticsRequestInitializer(API_KEY);
// Build the Analytics Service object
Analytics analytics = new Analytics.Builder(netHttpTransport, jacksonFactory, null)
.setAnalyticsRequestInitializer(analyticsInitializer)
.setApplicationName("ApiKeySample")
.build();
// Start coding cool things.
}
}
Python
from apiclient.discovery import build
API_KEY = 'YOUR API KEY'
def main(argv):
# Set the API Key and build the Analytics service object.
service = build('analytics', 'v3', developerKey=API_KEY)
# Start coding cool things.
1.199
require_once 'google-api-php-client/src/Google_Client.php'; require_once 'google-api-php-client/src/contrib/Google_AnalyticsService.php'; const API_KEY = 'YOUR API KEY' $client = new Google_Client(); // Set the API Key $client->setDeveloperKey($API_KEY); // Build the Analytics Service object. $analytics = new google_AnalyticsService($client); // Start coding cool things.
JavaScript
<!--
Method 1:
Using the Google APIs Client Library for JavaScript
-->
<script>
var apiKey = 'YOUR API KEY';
function handleClientLoad() {
gapi.client.setApiKey(apiKey);
gapi.client.load('analytics', 'v3', makeRequest);
}
function makeRequest() {
// Start coding cool things.
}
</script>
<script src="//apis.google.com/js/client.js?onload=handleClientLoad"></script>
<!--
Method 2:
Using REST and callback parameter
-->
<script>
function render() {
// Place your awesome code here.
}
</script>
<!-- Replace RESOURCE with the path to the Google Analytics resource you're querying. -->
<script src="https://www.googleapis.com/analytics/v3/RESOURCE/?key=YOUR_API_KEY&callback=render"></script>
Thuộc tính cột
Phản hồi của API siêu dữ liệu bao gồm một thuộc tính attributeNames liệt kê mọi thuộc tính cột hợp lệ. Mỗi cột có một thuộc tính attributes bao gồm một tập hợp con các thuộc tính
áp dụng cho cột đó.
Bảng sau đây là danh sách đầy đủ các thuộc tính hợp lệ:
Trường hợp Sử dụng
Bạn có thể dùng API siêu dữ liệu để giải quyết các trường hợp sử dụng sau:
- Các cột không dùng nữa
- Tên cột
- Cột cố định
- Cột được tính
- Cột và Phân đoạn
- Các phiên bản API
- Thẻ điện tử
Các cột không được chấp nhận
Nếu một cột (tức là phương diện hoặc chỉ số) không được dùng nữa, thì thuộc tính status của cột đó sẽ được đặt thành DEPRECATED.
Đoạn mã sau đây cho biết cách sử dụng thuộc tính status để kiểm tra xem một cột có bị ngừng sử dụng hay không:
function isDeprecated(column) {
return column.attributes.status == 'DEPRECATED';
}
Nếu một cột được đổi tên/xoá, thì thuộc tính status của cột đó sẽ được đặt thành DEPRECATED và có thể có thuộc tính replacedBy được đặt thành Id của cột thay thế.
Đoạn mã sau đây cho biết cách sử dụng thuộc tính replacedBy để lấy mã nhận dạng của cột thay thế:
function getReplacementId(column) {
return column.attributes.replacedBy;
}
Tên cột
Thuộc tính uiName là tên phương diện hoặc chỉ số được
sử dụng trong giao diện người dùng Google Analytics (ví dụ: giao diện web).
Đoạn mã sau cho biết cách truy xuất tên giao diện người dùng của một cột:
function getColumnName(column) {
return column.attributes.uiName;
}
Cột cố định
Các cột mẫu bao gồm phương diện hoặc chỉ số có chỉ mục dạng số.
Ví dụ: ga:goalXXStarts, ga:dimensionXX, ga:metricXX, v.v. Một cột mẫu sẽ có các thuộc tính minTemplateIndex và maxTemplateIndex xác định phạm vi chỉ mục.
Đoạn mã sau đây cho biết cách kiểm tra xem một cột có được tạo mẫu hay không:
function isTemplatized(column) {
return !!column.attributes.minTemplateIndex ||
!!column.attributes.maxTemplateIndex;
}
Đoạn mã sau đây cho biết cách truy xuất danh sách mã nhận dạng hợp lệ cho một cột mẫu:
function getTemplatizedIdList(column) {
var columnIdList = [];
var columnId = column.id;
if (isTemplatized(column)) {
minIndex = parseInt(column.attributes.minTemplateIndex);
maxIndex = parseInt(column.attributes.maxTemplateIndex);
for (var i = minIndex; i <= maxIndex; i++) {
columnIdList.push(columnId.replace('XX', i));
}
}
return columnIdList;
}
Cột được tính
Một cột bắt nguồn từ phép tính của các cột khác sẽ có thuộc tính calculation. Ví dụ: Cách tính ga:percentNewSessions là ga:newSessions / ga:sessions.
Ví dụ sau đây cho biết cách kiểm tra xem một cột có được tính hay không và cách truy xuất kết quả tính toán cho một cột:
function isCalculated(column) {
return !!column.attributes.calculation;
}
function getCalculation(column) {
return column.attributes.calculation;
}
Cột và Phân đoạn
Thuộc tính allowedInSegments cho phép bạn kiểm tra xem có thể sử dụng một cột trong tham số truy vấn phân đoạn hay không.
Ví dụ sau đây cho biết cách xác định xem một cột có thể sử dụng được trong các phân đoạn hay không:
function isAllowedInSegments(column) {
return !!column.attributes.allowedInSegments;
}
Đã thêm vào phiên bản API
Dùng thuộc tính addedInApiVersion để kiểm tra xem có thể dùng một cột trong API báo cáo của một phiên bản đã chỉ định hay không. Ví dụ: hãy gọi hàm sau để xác minh rằng cột đó có thể được sử dụng trong Core Reporting API phiên bản 3:
function isAllowedInV3(column) {
return column.attributes.addedInApiVersion < 4;
}
ETag
Mỗi phản hồi của API siêu dữ liệu đều có một ETag. ETag là một giá trị nhận dạng có thể dùng để lưu vào bộ nhớ đệm và cập nhật phản hồi của API siêu dữ liệu. Điều này rất quan trọng vì các cột (tức là phương diện và chỉ số) dữ liệu có thể không thay đổi trong thời gian dài và không hiệu quả trong việc thực hiện các yêu cầu và cập nhật không cần thiết khi có thể dùng dữ liệu đã lưu vào bộ nhớ đệm.
Nếu lưu trữ ETag của một tập hợp cột, bạn có thể dùng thẻ này theo 2 cách chủ yếu: kiểm tra xem phản hồi của API siêu dữ liệu đã lưu vào bộ nhớ đệm có cập nhật hay không và đưa vào yêu cầu API siêu dữ liệu.
Kiểm tra phản hồi được lưu trong bộ nhớ đệm
Nếu bạn so sánh giá trị ETag được trả về từ phản hồi của API siêu dữ liệu và giá trị đó tương đương với ETag của một tài nguyên đã lưu vào bộ nhớ đệm, thì tức là phiên bản đã lưu vào bộ nhớ đệm là phiên bản hiện tại. Nếu các ETag không tương đương, hãy cập nhật ứng dụng và làm mới bộ nhớ đệm bằng phản hồi mới nhất.
Nếu bạn chỉ muốn truy xuất giá trị ETag từ API siêu dữ liệu, hãy đặt tham số truy vấn trường
thành etag khi đưa ra yêu cầu.
Xem ví dụ.
Sử dụng ETag với yêu cầu API
Nếu có phiên bản tập hợp cột đã lưu vào bộ nhớ đệm, thì bạn có thể đưa giá trị ETag của tập hợp đó vào yêu cầu API siêu dữ liệu bằng cách thiết lập trường tiêu đề HTTP If-None-Match. API siêu dữ liệu sẽ kiểm tra giá trị ETag và phản hồi bằng phiên bản tài nguyên đã cập nhật cũng như trạng thái HTTP 200 OK hoặc phản hồi trống có trạng thái 304 Not
Modified nếu phiên bản đã lưu vào bộ nhớ đệm là mới nhất.