YouTube Analytics API - Data Model

API YouTube Analytics cho phép bạn tạo báo cáo tùy chỉnh chứa dữ liệu YouTube Analytics. API này hỗ trợ các báo cáo cho kênh và chủ sở hữu nội dung. Các trường báo cáo được mô tả như là phương diện hoặc chỉ số:

  • Phương diện là những tiêu chí phổ biến được dùng để tổng hợp dữ liệu, chẳng hạn như ngày xảy ra hành động hoặc quốc gia nơi người dùng đặt trụ sở.

    Trong một báo cáo, mỗi hàng dữ liệu có một tổ hợp giá trị phương diện duy nhất. Do đó, các phương diện bạn chọn cho báo cáo sẽ xác định cách YouTube tính giá trị cho các chỉ số trong báo cáo đó.

  • Chỉ số là các phép đo riêng lẻ liên quan đến hoạt động của người dùng, hiệu suất quảng cáo hoặc doanh thu ước tính. Chỉ số hoạt động của người dùng bao gồm những chỉ số như số lượt xem video và số lượt xếp hạng (lượt thích và lượt không thích).

API Analytics cung cấp các thông số lọc và sắp xếp, vì vậy, ứng dụng gọi không cần phải hỗ trợ sẵn các hàm đó. API này cũng cho phép bạn truy xuất dữ liệu cho các nhóm trong YouTube Analytics, trong đó nhóm là một tập hợp tùy chỉnh gồm tối đa 500 video, danh sách phát, kênh hoặc tài sản.

Chọn thông số báo cáo

Khi bạn yêu cầu báo cáo, sử dụng phương thức reports.query của API, yêu cầu API chứa 5 tham số xác định cách tính các giá trị báo cáo:

  • Các thông số startDate và endDate chỉ định khoảng thời gian mà báo cáo sẽ chứa dữ liệu. Phản hồi API thực sự chứa dữ liệu cho đến ngày cuối cùng được chỉ định mà tất cả chỉ số trong truy vấn có sẵn tại thời điểm truy vấn.

  • Tham số metrics chỉ định các số đo sẽ có trong báo cáo. Trong báo cáo kênh, các chỉ số đo lường hoạt động của người dùng và bao gồm những giá trị như số lượt xem và số lượt thích. Một số chỉ số cũng đo lường hiệu suất quảng cáo hoặc doanh thu ước tính.

  • Tham số dimensions giải thích cách các nhóm chỉ số sẽ được nhóm.

  • Thông số filters giải thích cách dữ liệu báo cáo sẽ được lọc. Vì vậy, thay vì trả về tất cả dữ liệu cho một kênh, báo cáo có thể được lọc để chỉ chứa chỉ số cho quốc gia, video hoặc nhóm video nhất định.

    Lưu ý: API cho phép bạn chỉ định nhiều giá trị cho các bộ lọc video, danh sách phát và kênh. Nếu làm như vậy, thì bạn cũng có thể đưa bộ lọc đó vào danh sách phương diện để các chỉ số được trả về cũng được nhóm theo video, danh sách phát hoặc kênh.

Tuỳ chọn báo cáo mẫu

Ví dụ: giả sử chủ sở hữu kênh muốn truy xuất báo cáo loại thiết bị video để xác định số lượt xem video của kênh xảy ra trên thiết bị di động, máy chơi trò chơi, TV, v.v.

  • Chủ sở hữu kênh đặt thông số startDate thành 2015-06-01 và thông số endDate thành 2015-07-31. Dựa trên các giá trị này, báo cáo sẽ chứa dữ liệu trong khoảng thời gian hai tháng.

  • Báo cáo loại thiết bị hỗ trợ các chỉ số lượt xem và estimatedMinutesMinutes nên chủ sở hữu kênh đặt tham số metrics thành views,estimatedMinutesWatched.

  • Chủ sở hữu kênh có một số tùy chọn đối với tham số dimensions. Hai trong số đó được hiển thị trong danh sách sau đây, và một phần ba được thảo luận trong phần giải thích về giá trị tham số filters ở phần sau.

    • Nếu bạn đặt giá trị thông số thành deviceType, thì số lượt xem và số thời gian xem sẽ được nhóm theo loại thiết bị trong toàn bộ khoảng thời gian báo cáo. Vì vậy, với giá trị này, dữ liệu báo cáo sẽ trả lời cho các câu hỏi như:

      • Video của kênh được xem trên thiết bị di động bao nhiêu lần từ ngày 1 tháng 6 năm 2015 đến ngày 31 tháng 7 năm 2015?
      • Video của kênh được xem trên máy chơi trò chơi bao nhiêu lần từ ngày 1 tháng 6 năm 2015 đến ngày 31 tháng 7 năm 2015?

      Báo cáo thực tế sẽ chứa tổng số lượt xem và thời gian xem của từng loại thiết bị.

    • Nếu bạn đặt giá trị thông số thành day,deviceType, thì số lượt xem và số thời gian xem sẽ được tính theo loại thiết bị mỗi ngày trong kỳ báo cáo. Vì vậy, với giá trị này, dữ liệu báo cáo sẽ trả lời cho các câu hỏi như:

      • Các video trên kênh đã được xem trên thiết bị di động bao nhiêu lần vào ngày 1 tháng 6 năm 2015?
      • Các video trên kênh đã được xem trên truyền hình bao nhiêu lần vào ngày 14/07/2015?

  • Cuối cùng, thông số filters cho phép chủ sở hữu kênh hạn chế báo cáo để chỉ bao gồm dữ liệu khớp với các giá trị bộ lọc cụ thể. Báo cáo này hỗ trợ quá nhiều tùy chọn lọc để giải thích tất cả các tùy chọn, do đó, những ví dụ này chỉ đại diện cho một phần báo cáo mà bạn có thể tạo.

    • Chủ sở hữu kênh có thể lọc yêu cầu để chỉ trả về các giá trị cho hệ điều hành Android. (Có bao nhiêu lượt xem đã xảy ra trên thiết bị di động Android trong kỳ báo cáo?)

    • Chủ sở hữu kênh có thể lọc yêu cầu chỉ trả về các giá trị cho một quốc gia cụ thể. (Mỗi ngày, chúng tôi đã xem video ở Canada bao nhiêu lần?

    • Chủ sở hữu kênh có thể lọc yêu cầu chỉ trả về các giá trị cho video cụ thể. Tuy nhiên, bộ lọc video hỗ trợ danh sách giá trị được phân tách bằng dấu phẩy, vì vậy, báo cáo thực sự có thể chứa dữ liệu cho nhiều video.

      Ngoài ra, nếu bộ lọc video chỉ định nhiều giá trị, thì bạn cũng có thể chỉ định video làm phương diện. Điều đó có nghĩa là tham số dimensions cũng hỗ trợ các giá trị deviceType,video và day,deviceType,video.

      • Nếu chủ sở hữu kênh đưa video vào danh sách phương diện, thì các chỉ số này sẽ chỉ định từng giá trị cho mỗi video. (Ngày 1 tháng 6 năm 2015, video XYZ được xem bao nhiêu lần trên máy chơi trò chơi?)
      • Nếu chủ sở hữu kênh không đưa video vào danh sách phương diện thì các chỉ số này sẽ chỉ định tổng giá trị cho tất cả các video được chỉ định. (Ngày 1 tháng 6 năm 2015, các video ABC, DEF và XYZ được xem trên máy chơi trò chơi bao nhiêu lần?)

Đang truy xuất báo cáo

Để truy xuất báo cáo, hãy gửi yêu cầu GET được cho phép đến phương thức reports.query của API, chỉ định tham số xác định báo cáo mà bạn muốn truy xuất.

Hãy xem tài liệu về báo cáo kênh và báo cáo chủ sở hữu nội dung để biết danh sách báo cáo mà API hỗ trợ. Mỗi định nghĩa báo cáo xác định các giá trị mà báo cáo cho phép đối với tham số metrics, dimensions và filters.

Các phương pháp hay nhất

Ứng dụng sử dụng API YouTube Analytics phải luôn tuân thủ những phương pháp sau:

  • Sử dụng hàng tiêu đề của phản hồi để xác định thứ tự của các cột trong báo cáo. Ví dụ: không giả định rằng lượt xem sẽ là chỉ số đầu tiên được trả về trong phản hồi chỉ vì đó là chỉ số đầu tiên được liệt kê trong phần mô tả báo cáo. Thay vào đó, hãy sử dụng hàng tiêu đề của phản hồi để xác định cột nào chứa dữ liệu đó.
  • Sử dụng API Dữ liệu YouTube để truy xuất siêu dữ liệu bổ sung cho những tài nguyên được xác định trong phản hồi của API YouTube Analytics. Như đã nêu trong Chính sách dành cho nhà phát triển dịch vụ API YouTube (mục III.E.4.b đến III.E.4.d), các ứng dụng API phải xoá hoặc làm mới siêu dữ liệu tài nguyên được lưu trữ khỏi API đó sau 30 ngày.

Dữ liệu tổng hợp và các mục đã xoá

Phản hồi của API YouTube Analytics không chứa bảng chi tiết chỉ số cho các mục đã xoá. Ví dụ: nếu một chủ sở hữu kênh xóa một video thì video đó sẽ không còn được liệt kê trong phản hồi API mà trả về chỉ số trên cơ sở từng video. Tuy nhiên, các báo cáo tổng hợp chỉ số cho một nhóm tài nguyên vẫn bao gồm các chỉ số liên kết với các mục đã xóa.

Ví dụ: giả sử một chủ sở hữu kênh truy xuất hai báo cáo. Báo cáo đầu tiên liệt kê tổng số lượt xem hằng ngày của tất cả các video trên kênh trong một khoảng thời gian cụ thể. Báo cáo thứ hai liệt kê tổng số lượt xem hằng ngày theo từng video trong cùng một khoảng thời gian.

Trong trường hợp này, các số liệu trong báo cáo đầu tiên sẽ bao gồm lượt xem các video sau đó đã bị xoá vì báo cáo đầu tiên chứa số liệu tổng hợp hằng ngày. Tuy nhiên, báo cáo thứ hai sẽ không bao gồm lượt xem được liên kết với các mục đã xóa vì báo cáo thứ hai liệt kê các lượt xem theo từng video. Kết quả là nếu kênh đã xóa video trong khoảng thời gian mà báo cáo đó tính đến, thì tổng số lượt xem hằng ngày được báo cáo trong báo cáo đầu tiên có thể cao hơn tổng số lượt xem hằng ngày của từng video cụ thể trong báo cáo thứ hai.

Ẩn danh dữ liệu

Một số dữ liệu trong YouTube Analytics sẽ bị giới hạn khi các chỉ số không đạt đến một ngưỡng nhất định. Điều này có thể xảy ra trong nhiều báo cáo. Trong thực tế, điều đó có nghĩa là một báo cáo có thể không chứa tất cả (hoặc bất kỳ) dữ liệu nào của bạn nếu:

  1. một video hoặc kênh bị giới hạn lưu lượng truy cập trong một khoảng thời gian cụ thể,

    hoặc

  2. bạn đã chọn một bộ lọc hoặc phương diện, chẳng hạn như nguồn lưu lượng truy cập hoặc quốc gia, trong đó các giá trị không đáp ứng một ngưỡng nhất định.

Trong trường hợp dữ liệu bị hạn chế, có thể có sự khác biệt giữa tổng số được báo cáo trong các báo cáo khác nhau, tuỳ thuộc vào cách các báo cáo đó tổng hợp dữ liệu.

Ví dụ: giả sử một chủ sở hữu kênh truy xuất hai báo cáo. Báo cáo đầu tiên liệt kê tổng số lượt xem cho một video cụ thể và báo cáo thứ hai liệt kê tổng số lượt xem cho video đó theo từng quốc gia. Trong khoảng thời gian chỉ định, giả sử video được xem 1000 lần, trong đó 500 lượt xem xảy ra ở Hoa Kỳ, 498 lượt xảy ra ở Canada và 200 lượt xảy ra ở Pháp.

Trong ví dụ này, báo cáo đầu tiên cho biết video đã được xem 1000 lần. Báo cáo thứ hai chỉ cho biết video đã được xem 500 lần ở Hoa Kỳ và 498 lần ở Canada. Như vậy, sẽ có sự khác biệt giữa tổng số lượt xem trong hai báo cáo. Lưu ý rằng báo cáo thứ hai không chứa bất kỳ chỉ báo nào cho thấy hai chế độ xem khác cũng đã xảy ra (hoặc bất kỳ lượt xem nào đã xảy ra ở Pháp).

Các ngưỡng thực tế mà dữ liệu bị giới hạn sẽ không được xuất bản và có thể thay đổi theo quyết định riêng của YouTube.

Loại dữ liệu bị hạn chế

Dữ liệu sau đây có thể bị giới hạn trong các báo cáo của YouTube Analytics:

  • Dữ liệu nhân khẩu học, chẳng hạn như độ tuổi và giới tính.
  • Dữ liệu địa lý, bao gồm cả các chỉ số hoặc phương diện liên quan đến quốc gia hoặc khu vực nơi người xem sinh sống, chẳng hạn như quốc gia hoặc khu vực của họ. Tuy nhiên, xin lưu ý rằng báo cáo không áp dụng các ngưỡng địa lý cho chỉ số doanh thu.
  • Chỉ số liên quan đến các nguồn lưu lượng truy cập cụ thể, chẳng hạn như cụm từ tìm kiếm hoặc URL bên ngoài, giúp mang lại lượt xem video của bạn. Ví dụ: những cụm từ tìm kiếm và URL dẫn đến số lượng lượt xem rất nhỏ sẽ không xuất hiện trong báo cáo, mặc dù bạn vẫn sẽ thấy những cụm từ và URL thúc đẩy nhiều người xem nội dung của mình.

Hãy tham khảo Trung tâm trợ giúp của YouTube để biết thêm thông tin về dữ liệu bị hạn chế trong báo cáo YouTube Analytics.

Mức sử dụng hạn mức

Mỗi yêu cầu API mà bạn thực hiện được tính là một đơn vị hạn mức sử dụng API. Giới hạn định mức được hiển thị trên bảng Hạn mức trong Google API Console.