API báo cáo phễu đa kênh – Hướng dẫn cho nhà phát triển

Tài liệu này giải thích cách sử dụng API Báo cáo phễu đa kênh để truy cập vào Dữ liệu về phễu đa kênh.

Giới thiệu

API Báo cáo Phễu đa kênh cho phép bạn truy cập vào dữ liệu dạng bảng trong báo cáo tuỳ chỉnh và báo cáo tiêu chuẩn về Phễu đa kênh. Để truy cập dữ liệu, bạn tạo một truy vấn chỉ định: chế độ xem (hồ sơ), ngày bắt đầu và ngày kết thúc, cũng như những phương diện và chỉ số tạo nên các tiêu đề cột trong bảng. Truy vấn này được gửi đến API Báo cáo phễu đa kênh và API Báo cáo phễu đa kênh sẽ trả về tất cả dữ liệu dưới dạng bảng.

Nếu bạn mới sử dụng API này, hãy đọc bài viết Tổng quan về API Báo cáo phễu đa kênh để biết phần giới thiệu về mục đích của API Báo cáo phễu đa kênh và dữ liệu mà API này cung cấp.

Trước khi bắt đầu

Hướng dẫn này sử dụng thư viện ứng dụng Java để truy cập vào API Báo cáo phễu đa kênh. Mỗi thư viện ứng dụng cung cấp một đối tượng dịch vụ Analytics duy nhất để gọi API Báo cáo phễu đa kênh nhằm lấy dữ liệu. Nếu bạn không sử dụng thư viện ứng dụng để truy cập API, hãy đọc API Báo cáo phễu đa kênh – Hướng dẫn tham khảo.

Cách tạo đối tượng dịch vụ Analytics:

  1. Đăng ký ứng dụng của bạn trong Google API Console.
  2. Uỷ quyền truy cập vào dữ liệu Google Analytics.
  3. Viết mã để tạo đối tượng dịch vụ Analytics.

Nếu bạn chưa hoàn tất những bước này, hãy dừng lại và đọc Hướng dẫn về API Hello Analytics. Đây là tài liệu hướng dẫn bạn về các bước đầu tiên để tạo ứng dụng API Google Analytics. Sau khi xem xong, hãy tiếp tục đọc hướng dẫn sau.

Ví dụ: mã sau đây tạo một đối tượng dịch vụ Analytics được uỷ quyền:

Java

Analytics analytics = initializeAnalytics();

Sử dụng đối tượng dịch vụ Analytics analytics để gọi API Báo cáo phễu đa kênh.

Tổng quan

Để sử dụng API Báo cáo phễu đa kênh nhằm truy xuất dữ liệu, hãy ghi một ứng dụng vào:

  1. Truy vấn API Báo cáo phễu đa kênh.
  2. Xử lý các kết quả mà API trả về.

Truy vấn API Báo cáo phễu đa kênh

Cách yêu cầu dữ liệu từ API Báo cáo phễu đa kênh:

  1. Tạo đối tượng truy vấn API Báo cáo Phễu đa kênh.
  2. Sử dụng đối tượng truy vấn để yêu cầu dữ liệu từ các máy chủ Phễu đa kênh.

Tạo truy vấn API Báo cáo phễu đa kênh

Để tạo đối tượng truy vấn API Báo cáo Phễu đa kênh, hãy gọi phương thức này:

analytics.data.mcf.get()    // analytics is the Analytics service object

Thông số đầu tiên được cung cấp cho phương thức này là một mã bảng duy nhất ở dạng ga:XXXX, trong đó XXXX là mã của một chế độ xem (hồ sơ) Analytics chứa dữ liệu được yêu cầu. Sử dụng đối tượng truy vấn để chỉ định các tham số truy vấn (tức là setDimensions). Ví dụ:

Java

Get apiQuery = analytics.data().mcf()
    .get(tableId,
        "2012-01-01",              // Start date
        "2012-03-31",              // End date
        "mcf:totalConversions")    // Metrics
    .setDimensions("mcf:sourcePath")
    .setSort("-mcf:totalConversions")
    .setMaxResults(25);

Để biết danh sách tất cả các tham số truy vấn, hãy xem Tóm tắt tham số truy vấn. Các thông số chỉ số và phương diện cho phép bạn chỉ định dữ liệu nào cần truy xuất từ Phễu đa kênh. Để biết danh sách tất cả các phương diện và chỉ số, hãy xem Tài liệu tham khảo về phương diện và chỉ số.

Tạo yêu cầu dữ liệu API Báo cáo phễu đa kênh

Sau khi tạo đối tượng truy vấn, hãy gọi phương thức execute trên đối tượng đó để yêu cầu dữ liệu từ các máy chủ Phễu đa kênh. Ví dụ:

Java

try {
  apiQuery.execute();
  // Success. Do something cool!

} catch (GoogleJsonResponseException e) {
  // Catch API specific errors.
  handleApiError(e);

} catch (IOException e) {
  // Catch general parsing network errors.
  e.printStackTrace();
}

Thay vào đó, nếu bạn muốn truy cập vào phản hồi thô của API, hãy gọi phương thức executeUnparsed() trên đối tượng truy vấn:

HttpResponse response = apiQuery.executeUnparsed();

Nếu truy vấn thành công, truy vấn sẽ trả về dữ liệu được yêu cầu. Nếu xảy ra lỗi, phương thức execute sẽ gửi một ngoại lệ chứa mã trạng thái cho lỗi và nội dung mô tả lỗi. Ứng dụng sẽ phát hiện và xử lý ngoại lệ.

Xử lý các kết quả API

Nếu truy vấn API Báo cáo Phễu đa kênh thành công, yêu cầu này sẽ trả về dữ liệu báo cáo và thông tin về dữ liệu.

Dữ liệu báo cáo Phễu đa kênh

Truy vấn này trả về dữ liệu báo cáo dạng bảng sau đây:

  • Dữ liệu tiêu đề cột
  • Dữ liệu hàng

Dữ liệu tiêu đề cột

Phản hồi truy vấn có trường tiêu đề cột chứa thông tin tiêu đề bảng. Trường này là một danh sách (hoặc một mảng) gồm các đối tượng ColumnHeaders, mỗi đối tượng chứa tên cột, loại cột và loại dữ liệu cột. Thứ tự cột là các cột phương diện, theo sau là các cột chỉ số theo cùng thứ tự được chỉ định trong truy vấn ban đầu. Ví dụ: phương thức sau in tiêu đề cột:

Java

private static void printColumnHeaders(McfData mcfData) {
  System.out.println("Column Headers:");

  for (ColumnHeaders header : mcfData.getColumnHeaders()) {
    System.out.println("Column Name: " + header.getName());
    System.out.println("Column Type: " + header.getColumnType());
    System.out.println("Column Data Type: " + header.getDataType());
  }
}

Dữ liệu hàng

Dữ liệu chính mà API trả về sẽ được trả về dưới dạng List 2 chiều của McfData.Rows. Mỗi McfData.Rows đại diện cho một ô duy nhất là giá trị gốc của loại String hoặc giá trị đường dẫn chuyển đổi thuộc loại McfData.Rows.ConversionPathValue. Thứ tự của các ô trong một hàng giống với các trường trong đối tượng tiêu đề cột được mô tả ở trên.

Vì dữ liệu trong mỗi ô được trả về dưới dạng chuỗi hoặc loại trình tự Phễu đa kênh, nên trường DataType trong mỗi đối tượng tiêu đề cột đặc biệt hữu ích cho việc phân tích cú pháp các giá trị thành loại thích hợp. Hãy xem hướng dẫn tham khảo để biết tất cả các loại dữ liệu có thể có.

Ví dụ: phương thức sau in tiêu đề và hàng của bảng:

Java

private static void printDataTable(McfData mcfData) {
  System.out.println("Data Table:");
  if (mcfData.getTotalResults() > 0) {
    // Print the column names.
    List<ColumnHeaders> headers = mcfData.getColumnHeaders();
    for (ColumnHeaders header : headers) {
      System.out.print(header.getName());
    }
    System.out.println();

    // Print the rows of data.
    for (List<McfData.Rows> row : mcfData.getRows()) {
      for (int columnIndex = 0; columnIndex < row.size(); ++columnIndex) {
        ColumnHeaders header = headers.get(columnIndex);
        McfData.Rows cell = row.get(columnIndex);
        if (header.getDataType().equals("MCF_SEQUENCE")) {
          System.out.print(getStringFromMcfSequence(cell.getConversionPathValue()));
        } else {
          System.out.print(cell.getPrimitiveValue());
        }
      }
      System.out.println();
    }
  } else {
    System.out.println("No rows found");
  }
}

Ví dụ sau cho thấy cách phân tích cú pháp một đối tượng loại trình tự Phễu đa kênh và chuyển đổi đối tượng đó thành chuỗi:

Java

private static String getStringFromMcfSequence(List<McfData.Rows.ConversionPathValue> path) {
  StringBuilder stringBuilder = new StringBuilder();
  for (McfData.Rows.ConversionPathValue pathElement : path) {
    if (stringBuilder.length() > 0)
      stringBuilder.append(" > ");
    stringBuilder.append(pathElement.getNodeValue());
  }
  return stringBuilder.toString();
}

Thông tin báo cáo

Ngoài dữ liệu báo cáo, truy vấn này còn trả về thông tin (ví dụ: mã báo cáo) về dữ liệu. Ví dụ: phương thức sau in thông tin báo cáo:

Java

private static void printReportInfo(McfData mcfData) {
  System.out.println("Report Info:");
  System.out.println("ID:" + mcfData.getId());
  System.out.println("Self link: " + mcfData.getSelfLink());
  System.out.println("Kind: " + mcfData.getKind());
  System.out.println("Contains Sampled Data: " + mcfData.getContainsSampledData());
}

Trường containsSampledData cho bạn biết liệu phản hồi truy vấn đã được lấy mẫu hay chưa. Vì việc lấy mẫu có thể ảnh hưởng đến kết quả truy vấn, nên các giá trị được lấy mẫu mà truy vấn (API) trả về sẽ không khớp với các giá trị xuất hiện trên giao diện web. Hãy xem phần Lấy mẫu để biết thêm thông tin chi tiết.

Thông tin về chế độ xem (Hồ sơ)

Phản hồi truy vấn bao gồm ID thuộc tính web, tên và ID chế độ xem (hồ sơ) cũng như ID của tài khoản Analytics chứa chế độ xem (hồ sơ). Ví dụ: phương thức sau in các giá trị đó ra thiết bị đầu cuối (đầu ra chuẩn):

Java

private static void printProfileInfo(McfData mcfData) {
  ProfileInfo profileInfo = mcfData.getProfileInfo();

  System.out.println("View (Profile) Info:");
  System.out.println("Account ID: " + profileInfo.getAccountId());
  System.out.println("Web Property ID: " + profileInfo.getWebPropertyId());
  System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId());
  System.out.println("View (Profile) ID: " + profileInfo.getProfileId());
  System.out.println("View (Profile) Name: " + profileInfo.getProfileName());
  System.out.println("Table ID: " + profileInfo.getTableId());
}

Thông tin về truy vấn

Phản hồi truy vấn bao gồm đối tượng Query chứa giá trị của tất cả tham số truy vấn yêu cầu dữ liệu. Ví dụ: phương thức sau in giá trị của các tham số như vậy:

Java

private static void printQueryInfo(McfData mcfData) {
  Query query = mcfData.getQuery();

  System.out.println("Query Info:");
  System.out.println("Ids: " + query.getIds());
  System.out.println("Start Date: " + query.getStartDate());
  System.out.println("End Date: " + query.getEndDate());
  System.out.println("Metrics: " + query.getMetrics());       // List of Analytics metrics
  System.out.println("Dimensions: " + query.getDimensions()); // List of Analytics dimensions
  System.out.println("Sort: " + query.getSort());             // List of sorte metrics or dimensions
  System.out.println("Segment: " + query.getSegment());
  System.out.println("Filters: " + query.getFilters());
  System.out.println("Start Index: " + query.getStartIndex());
  System.out.println("Max Results: " + query.getMaxResults());
}

Các phương thức không phải query.getMetrics(), query.getDimensions() và query.getSort() sẽ trả về String. Ví dụ: query.getStartDate() trả về ngày bắt đầu (String) của báo cáo.

Thông tin phân trang

Mọi yêu cầu API Báo cáo phễu đa kênh đều có thể khớp với hàng trăm nghìn hàng của dữ liệu Phễu đa kênh. API Báo cáo phễu đa kênh sẽ chỉ trả về một tập hợp con, được gọi là một trang dữ liệu, tại một thời điểm nhất định. Để truy xuất tất cả các trang dữ liệu, hãy sử dụng trường phân trang. Phương thức sau in thông tin về tính năng phân trang:

Java

private static void printPaginationInfo(McfData mcfData) {
  System.out.println("Pagination Info:");
  System.out.println("Previous Link: " + mcfData.getPreviousLink());
  System.out.println("Next Link: " + mcfData.getNextLink());
  System.out.println("Items Per Page: " + mcfData.getItemsPerPage());
  System.out.println("Total Results: " + mcfData.getTotalResults());
}

Lệnh gọi phương thức mcfData.getTotalResults() trả về tổng số hàng cho truy vấn, có thể lớn hơn tổng số hàng mà truy vấn trả về. Và lệnh gọi phương thức mcfData.getItemsPerPage() sẽ trả về số lượng hàng tối đa mà phản hồi truy vấn có thể chứa.

Lệnh gọi phương thức mcfData.getPreviousLink() trả về đường liên kết đến trang trước và mcfData.getNextLink() trả về đường liên kết đến trang tiếp theo.

Tổng số cho tất cả kết quả

Để biết tổng giá trị của các chỉ số yêu cầu trên tất cả kết quả, chứ không chỉ kết quả được trả về trong phản hồi truy vấn, hãy gọi phương thức getTotalsForAllResults() trên phản hồi truy vấn, một đối tượng McfData. Sử dụng các giá trị tổng để tính toán giá trị trung bình.

Java

private static void printTotalsForAllResults(McfData mcfData) {
  System.out.println("Metric totals over all results:");
  Map<String, String> totalsMap = mcfData.getTotalsForAllResults();
  for (Map.Entry<String, String> entry : totalsMap.entrySet()) {
    System.out.println(entry.getKey() + " : " + entry.getValue());
  }
}

Mẫu đang hoạt động

Java

Thư viện ứng dụng Java của Google API Mẫu API báo cáo phễu đa kênh