YouTube Analytics API - Data Model

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

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

  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 riêng biệt. Do đó, các phương diện mà bạn chọn cho một báo cáo sẽ xác định cách YouTube tính toán các giá trị cho chỉ số trong báo cáo đó.

• Chỉ số là các số đ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. Các chỉ số về hoạt động của người dùng bao gồm những yếu tố như số lượt xem video và điểm xếp hạng (lượt thích và lượt không thích).

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

Chọn các tham số báo cáo

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

• Các tham 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 của API thực tế chứa dữ liệu cho đến ngày cuối cùng được chỉ định mà tất cả các chỉ số trong truy vấn đều có sẵn tại thời điểm truy vấn.

• Tham số metrics chỉ định những chỉ số sẽ được đưa vào báo cáo. Trong báo cáo về 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ư lượt xem và 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 nhóm các chỉ số.

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

  Lưu ý: API này 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, bạn cũng có thể thêm 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.

Các lựa chọn báo cáo mẫu

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

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

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

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

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

    • Số lần video của kênh được xem trên thiết bị di động trong khoảng thời gian từ ngày 1 tháng 6 năm 2015 đến ngày 31 tháng 7 năm 2015 là bao nhiêu?
    • Từ ngày 1 tháng 6 năm 2015 đến ngày 31 tháng 7 năm 2015, video trên kênh này được xem bao nhiêu lần trên máy chơi trò chơi?

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

  • Khi bạn đặt giá trị tham số thành day,deviceType, số lượt xem và thời gian xem sẽ được tính theo loại thiết bị cho mỗi ngày trong 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 những câu hỏi như:

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

• Cuối cùng, tham 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 lựa chọn lọc để có thể giải thích hết tất cả. Vì vậy, những ví dụ này chỉ đại diện cho một phần nhỏ trong số các 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 trên thiết bị di động Android trong khoảng thời gian báo cáo?)

  • Chủ sở hữu kênh có thể lọc yêu cầu để chỉ trả về giá trị cho một quốc gia cụ thể. (Số lần video được xem ở Canada vào mỗi ngày trong khoảng thời gian báo cáo?)

  • Chủ sở hữu kênh có thể lọc yêu cầu để chỉ trả về giá trị cho một số video cụ thể. Tuy nhiên, bộ lọc video hỗ trợ danh sách các giá trị phân tách bằng dấu phẩy, nên báo cáo 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 thêm video vào danh sách các phương diện, thì các chỉ số sẽ chỉ định giá trị riêng lẻ cho từng video. (Video XYZ được xem bao nhiêu lần trên máy chơi trò chơi vào ngày 1 tháng 6 năm 2015?)
    • Nếu chủ sở hữu kênh không đưa video vào danh sách các phương diện, thì các chỉ số sẽ chỉ định tổng giá trị bao gồm tất cả video được chỉ định. (Có bao nhiêu lần video ABC, DEF và XYZ được xem trên máy chơi trò chơi vào ngày 1 tháng 6 năm 2015?)

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

Để truy xuất báo cáo, hãy gửi một yêu cầu GET được uỷ quyền đến phương thức reports.query của API, chỉ định các 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 các báo cáo mà API này 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 các tham số metrics, dimensions và filters.

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

Các ứng dụng sử dụng YouTube Analytics API luôn phải 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ụ: đừng giả định rằng views sẽ là chỉ số đầu tiên được trả về trong một 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 chứa dữ liệu đó.
• Sử dụng YouTube Data API để truy xuất siêu dữ liệu bổ sung cho các tài nguyên được xác định trong phản hồi của YouTube Analytics API. Như đã nêu trong Chính sách dành cho nhà phát triển của 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 đã lưu trữ từ API đó sau 30 ngày.

Các chỉ số tổng hợp và mục đã xoá

Phản hồi của YouTube Analytics API không chứa thông tin chi tiết về chỉ số của các mục đã bị xoá. Ví dụ: Nếu chủ sở hữu kênh xoá một video, thì video đó sẽ không còn xuất hiện trong phản hồi API trả về các chỉ số theo từng video. Tuy nhiên, những 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 quan đến các mục đã xoá.

Ví dụ: giả sử một chủ sở hữu kênh truy xuất 2 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ả 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 cho từng video trong cùng khoảng thời gian.

Trong trường hợp này, số liệu trong báo cáo đầu tiên sẽ bao gồm cả số lượt xem của những video sau đó bị xoá, vì báo cáo đầu tiên chứa dữ 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 liên quan đến các mục đã bị xoá vì báo cáo này liệt kê lượt xem theo từng video. Do đó, nếu kênh đã xoá video trong khoảng thời gian mà báo cáo đề cập, 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 trong báo cáo thứ hai.

Ẩn danh dữ liệu

Một số dữ liệu trong YouTube Analytics bị giới hạn khi các chỉ số không đạt một ngưỡng nhất định. Điều này có thể xảy ra trong nhiều loại báo cáo. Trên thực tế, điều này có nghĩa là 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. video hoặc kênh có lưu lượng truy cập bị giới hạn 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) có những giá trị không đáp ứng một ngưỡng nhất định.

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

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

Trong ví dụ này, báo cáo đầu tiên sẽ cho biết video có 1.000 lượt xem. Báo cáo thứ hai sẽ chỉ cho biết rằng video có 500 lượt xem ở Hoa Kỳ và 498 lượt xem ở Canada. Do vậy, tổng số lượt xem ở hai báo cáo này sẽ khác nhau. Xin lưu ý rằng báo cáo thứ hai sẽ không cho biết 2 lượt xem còn lại cũng đã xảy ra (hoặc bất kỳ lượt xem nào đã xảy ra ở Pháp).

Chúng tôi không công bố các ngưỡng giới hạn thực tế đối với dữ liệu và các ngưỡng này có thể thay đổi theo quyết định của YouTube.

Các loại dữ liệu bị hạn chế

Những dữ liệu sau 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 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 ngưỡng địa lý cho các chỉ số doanh thu.
• Các chỉ số liên quan đến những 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 dẫn đến lượt xem video của bạn. Ví dụ: những cụm từ tìm kiếm và URL dẫn đến rất ít lượt xem 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 thu hút nhiều người xem đến với nội dung của bạn.

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

Hạn mức sử dụng

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