Introduction

Tài liệu này giải thích những điểm tương đồng và khác biệt trong những cách mà API YouTube Analytics và API Báo cáo của YouTube cấp quyền truy cập vào dữ liệu của YouTube Analytics. Mục đích của tài liệu này là giúp bạn chọn đúng API cho ứng dụng của mình.

Cả hai API đều cho phép nhà phát triển truy xuất dữ liệu YouTube Analytics. Ngoài ra, cả hai API này đều hỗ trợ chủ sở hữu kênh YouTube và chủ sở hữu nội dung trên YouTube, mỗi người trong số họ đều có thể truy cập vào một nhóm các báo cáo cụ thể:

  • Báo cáo kênh chứa chỉ số hoạt động của người dùng trên một kênh cụ thể.

  • Báo cáo chủ sở hữu nội dung tổng hợp chỉ số cho tất cả các kênh liên kết với một chủ sở hữu nội dung cụ thể trên YouTube. Ví dụ: Một hãng thu âm có thể truy xuất báo cáo chứa số liệu thống kê tổng hợp về các kênh YouTube của tất cả nghệ sĩ thuộc hãng thu âm. Một số báo cáo của chủ sở hữu nội dung chứa chỉ số hoạt động của người dùng, trong khi một số báo cáo khác chứa chỉ số liên quan đến doanh thu và hiệu suất quảng cáo.

API Báo cáo cũng cho phép một số chủ sở hữu nội dung truy cập vào báo cáo doanh thu từ quảng cáo do hệ thống quản lý. Bạn chỉ có thể truy xuất dữ liệu trong báo cáo do hệ thống quản lý bằng API Báo cáo.

Tất cả yêu cầu về YouTube Analytics và API Báo cáo phải được kênh hoặc chủ sở hữu nội dung sở hữu dữ liệu yêu cầu uỷ quyền.

Nội dung báo cáo

Báo cáo mà các API truy xuất chứa hai loại dữ liệu:

  • Phương diện là những tiêu chí phổ biến dùng để tổng hợp dữ liệu, chẳng hạn như ngày diễn ra hoạt động của người dù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 đó, tổ hợp các giá trị phương diện của mỗi hàng sẽ đóng vai trò là khoá chính cho hàng đó.

  • Chỉ số là các dữ liệu đo lường riêng lẻ về 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 và điểm xếp hạng (lượt thích và lượt không thích video).

Chọn đúng API cho ứng dụng của bạn

API YouTube Analytics
API YouTube Analytics hỗ trợ các truy vấn được nhắm mục tiêu theo thời gian thực để tạo báo cáo YouTube Analytics tùy chỉnh. API này 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 phải hỗ trợ sẵn các hàm này.

Mỗi yêu cầu API chỉ định phạm vi ngày mà dữ liệu sẽ được trả về. API này cũng cho phép bạn truy xuất các tập dữ liệu hằng tuần và hằng tháng. Do đó, ứng dụng gọi không cần lưu trữ tập dữ liệu được truy xuất hoặc số liệu thống kê tổng hợp trong các phạm vi ngày.
API Báo cáo của YouTube
YouTube Reporting API truy xuất hàng loạt báo cáo chứa dữ liệu trong YouTube Analytics cho kênh hoặc chủ sở hữu nội dung. API này được thiết kế cho các ứng dụng có thể nhập các tập dữ liệu lớn và cung cấp các công cụ để lọc, sắp xếp và khai thác dữ liệu đó.

Mỗi báo cáo chứa một tập hợp các trường được xác định trước. Nhà phát triển sử dụng API này để lên lịch cho các công việc báo cáo, mỗi công việc trong số này xác định một báo cáo mà YouTube sẽ tạo. Sau đó, YouTube sẽ tạo một báo cáo hằng ngày có thể tải xuống không đồng bộ. Mỗi báo cáo chứa dữ liệu trong một khoảng thời gian 24 giờ riêng biệt.

Ngoài ra, YouTube tự động tạo một nhóm báo cáo do hệ thống quản lý cho những chủ sở hữu nội dung có quyền truy cập vào các báo cáo tương ứng trong YouTube Creator Studio. Các báo cáo này cung cấp quyền truy cập có lập trình vào dữ liệu doanh thu từ quảng cáo.

Các báo cáo được hỗ trợ

Bảng sau xác định các loại báo cáo khác nhau mà bạn có thể truy xuất bằng cách sử dụng API. Truy vấn được nhắm mục tiêu được cung cấp thông qua API YouTube Analytics, còn báo cáo hàng loạt được cung cấp thông qua API Báo cáo của YouTube.

Dữ liệu có trong API này có thể không xuất hiện trong API khác. Ví dụ: API YouTube Analytics cho phép bạn truy xuất chỉ số hoạt động của người dùng hằng tuần hoặc hằng tháng, nhưng API Báo cáo của YouTube yêu cầu bạn tự tổng hợp dữ liệu đó. Mặt khác, API Báo cáo YouTube hỗ trợ báo cáo tài sản cho chủ sở hữu nội dung nhưng dữ liệu đó không có sẵn từ API YouTube Analytics.

Loại báo cáo
Báo cáo video Được hỗ trợ cho các kênh (truy vấn hoặc hàng loạt) và chủ sở hữu nội dung (truy vấn hoặc hàng loạt).

Báo cáo video cung cấp số liệu thống kê về tất cả hoạt động của người dùng liên quan đến video của một kênh hoặc video của chủ sở hữu nội dung. Ví dụ: các báo cáo này chứa số lượt xem mà video của bạn nhận được. Trong API YouTube Analytics, một số báo cáo về video của chủ sở hữu nội dung cũng bao gồm các chỉ số về doanh thu ước tính và hiệu suất quảng cáo.
Báo cáo danh sách phát Được hỗ trợ cho các kênh (truy vấn hoặc hàng loạt) và chủ sở hữu nội dung (truy vấn hoặc hàng loạt).

Báo cáo danh sách phát cung cấp số liệu thống kê liên quan cụ thể đến các lượt xem video xuất hiện trong danh sách phát. API Báo cáo của YouTube hỗ trợ báo cáo tỷ lệ giữ chân người xem cho danh sách phát, nhưng API YouTube Analytics không hỗ trợ báo cáo tương tự.
Báo cáo hiệu quả hoạt động của quảng cáo Được hỗ trợ cho chủ sở hữu nội dung (truy vấn hoặc hàng loạt).

Báo cáo hiệu suất quảng cáo cung cấp chỉ số dựa trên số lượt hiển thị cho quảng cáo chạy trong lúc phát video. Các chỉ số này tính đến mỗi lượt hiển thị quảng cáo và mỗi lượt phát video có thể mang lại nhiều lượt hiển thị.
Báo cáo doanh thu ước tính Được hỗ trợ cho chủ sở hữu nội dung (hàng loạt).

Báo cáo Doanh thu ước tính cho biết tổng doanh thu ước tính của các video từ những nguồn quảng cáo do Google bán và từ các nguồn không phải quảng cáo. Những báo cáo này cũng chứa một số chỉ số về hiệu suất quảng cáo. Lưu ý rằng báo cáo do hệ thống quản lý chứa doanh thu thực tế.
Báo cáo thành phần Được hỗ trợ cho chủ sở hữu nội dung (hàng loạt).

Báo cáo tài sản cung cấp chỉ số hoạt động của người dùng liên quan đến những video có liên kết với tài sản của chủ sở hữu nội dung. Video được đưa vào báo cáo của chủ sở hữu nội dung nếu chủ sở hữu nội dung đã xác nhận quyền sở hữu video đó là video trùng khớp với một trong các tài sản của chủ sở hữu nội dung đó. Video có thể đã được chủ sở hữu nội dung hoặc một người dùng YouTube khác tải lên.
Báo cáo do hệ thống quản lý Được hỗ trợ cho những chủ sở hữu nội dung có quyền truy cập vào các báo cáo tương ứng trong trình đơn Báo cáo của YouTube Studio.

Báo cáo do hệ thống quản lý cung cấp dữ liệu doanh thu thực tế mà tài sản và video kiếm được. Một báo cáo bổ sung liệt kê các video đã được xác nhận quyền sở hữu và tài sản trùng khớp với những video đó. Lưu ý: Hiện tại, không phải báo cáo nào trong Creator Studio cũng có trong API.

Lưu ý: YouTube tự động tạo báo cáo do hệ thống quản lý cho những chủ sở hữu nội dung có quyền truy cập vào báo cáo tương ứng trong YouTube Studio. Do đó, quy trình truy xuất các báo cáo này khác với quy trình cho các loại báo cáo khác trong danh sách này. Xem tài liệu về báo cáo do hệ thống quản lý để biết thêm thông tin.

Các điểm khác biệt chính

Bảng sau đây nêu bật những điểm khác biệt quan trọng giữa YouTube Analytics và các API Báo cáo.

Tính năng API YouTube Analytics API Báo cáo của YouTube
Quy trình truy xuất dữ liệu Mỗi yêu cầu API chỉ định các phương diện và chỉ số cần trả về, cũng như khoảng thời gian mà dữ liệu sẽ được trả về. Ứng dụng lên lịch công việc báo cáo. Đối với mỗi công việc, YouTube sẽ tạo các báo cáo hằng ngày có thể tải xuống không đồng bộ.
Phạm vi ngày Một số báo cáo API chỉ định ngày mà hoạt động của người dùng xảy ra. Một số báo cáo trong số đó hỗ trợ các phương diện để tổng hợp chỉ số hoạt động của người dùng theo tháng. Tất cả các báo cáo API đều chỉ định ngày diễn ra hoạt động của người dùng. Các ứng dụng sử dụng API có thể triển khai các tính năng để tổng hợp dữ liệu trong các khoảng thời gian định kỳ.
Lọc dữ liệu Bạn có thể lọc báo cáo để chỉ bao gồm những hàng mà phương diện có một giá trị cụ thể. API này cũng hỗ trợ một số phương diện như lục địasubContinent chỉ được dùng làm bộ lọc. API hỗ trợ tải xuống hàng loạt tập dữ liệu hoàn chỉnh. Chế độ này không hỗ trợ tính năng lọc hoặc trả về dữ liệu cho các phương diện chỉ dùng bộ lọc. Ứng dụng lưu trữ dữ liệu đã tải xuống và triển khai các tính năng riêng để lọc dữ liệu.
Sắp xếp Có thể sắp xếp báo cáo dựa trên các giá trị chỉ số được trả về. Một số báo cáo chỉ hỗ trợ một số ít kết quả. Ví dụ: báo cáo liệt kê các video có nhiều lượt xem nhất của kênh sẽ trả về tối đa 200 hàng. API này hỗ trợ tải hàng loạt tập dữ liệu hoàn chỉnh xuống. Các ứng dụng khách có thể triển khai các tính năng riêng để sắp xếp dữ liệu đã tải xuống.
Bảng liệt kê Báo cáo API chứa các giá trị văn bản, chẳng hạn như "ANDROID" hoặc "CHANNEL" để xác định các giá trị phương diện được liệt kê. Báo cáo API chứa số nguyên có thể được ánh xạ tới giá trị văn bản.
Hạn mức Máy chủ API đánh giá từng truy vấn để xác định hạn mức truy vấn. Phần sử dụng hạn mức sẽ giải thích chi tiết hơn về phương pháp này. Sử dụng hạn mức không phải là vấn đề vì dữ liệu được truy xuất một lần và sau đó được lọc, sắp xếp và truy vấn trong ứng dụng.
Báo cáo riêng biệt
  • Hoạt động của người dùng liên quan đến phụ đề
  • Dữ liệu tỷ lệ giữ chân người xem cho danh sách phát
  • Báo cáo doanh thu ước tính cho chủ sở hữu nội dung (có 2 báo cáo khác nhau)
  • Báo cáo tài sản dành cho chủ sở hữu nội dung (có 11 báo cáo khác nhau)
Phương diện duy nhất nhóm (phương diện chỉ có bộ lọc)
lục địa (phương diện chỉ để lọc)
subContinent (phương diện chỉ có bộ lọc)
tháng
isCurated==1 (phương diện chỉ lọc)
viewsPerPlaylistStart
averageTimeInPlaylist
annotation_id
annotation_type
asset_id
card_id
card_type
live_or_on_demand
subscribed_status
subtitle_language
Các chỉ số riêng biệt đơn_nhất
relativeRetentionPerformance
viewsPerPlaylistStart
averageTimeInPlaylist
card_click_rate
card_clicks
card_impressions
card_teaser_click_rate
card_teaser_clicks
card_teaser_impressions
estimated_partner_adsense_revenue
estimated_partner_doubleclick_revenue{/16_
}danh_sách_phát_danh_sách_mua_hàng{/16_}{/17 2
playlist_saves_addedplaylist_saves_removed

Cách đặt tên khác biệt giữa các API

Hai API này hiện sử dụng quy ước đặt tên khác nhau để xác định thứ nguyên và chỉ số. Hiện tại, tên API YouTube Analytics sử dụng quy ước viết hoa kiểu lạc đà, còn tên API Báo cáo YouTube sử dụng tên được phân tách bằng dấu gạch dưới.

Bảng sau đây xác định các tên khác nhau mà 2 API sử dụng để xác định các chỉ số và phương diện giống nhau. Trong một số trường hợp, sự khác biệt giữa hai tên nhiều hơn những gì bạn nhận được sau khi chuyển đổi tên từ quy ước viết hoa kiểu lạc đà sang dấu gạch dưới. Ví dụ: phương diện video trong API YouTube Analytics có tên là video_id trong API Báo cáo của YouTube.

Kích thước

Tên API YouTube Analytics Tên API Báo cáo của YouTube
adType ad_type
ageGroup age_group
thành phần asset_id
audienceType audience_retention_type
kênh channel_id
claimedStatus claimed_status
contentOwner content_owner_id
country country_code
ngày date
deviceType device_type
elapsedVideoTimeRatio elapsed_video_time_percentage
gender [giới_tính] gender [giới_tính]
insightPlaybackLocationDetail playback_location_detail
insightPlaybackLocationType playback_location_type
insightTrafficSourceDetail traffic_source_detail
insightTrafficSourceType traffic_source_type
liveOrOnDemand live_or_on_demand
operatingSystem operating_system
danh sách phát playlist_id
province province_code
sharingService sharing_service
subscribedStatus subscribed_status
subtitleLanguage subtitle_language
uploaderType uploader_type
video video_id

Chỉ số

Tên API YouTube Analytics Tên API Báo cáo của YouTube
adEarnings estimated_partner_ad_revenue
annotationImpressions annotation_impressions
annotationClickableImpressions annotation_clickable_impressions
annotationClicks annotation_clicks
annotationClickThroughRate annotation_click_through_rate
annotationClosableImpressions annotation_closable_impressions
annotationCloses annotation_closes
annotationCloseRate annotation_close_rate
audienceWatchRatio audience_retention_percentage
averageViewDuration average_view_duration_seconds
averageViewPercentage average_view_duration_percentage
cardClickRate card_click_rate
cardClicks card_clicks
cardImpressions card_impressions
cardTeaserClickRate card_teaser_click_rate
cardTeaserClicks card_teaser_clicks
cardTeaserImpressions card_teaser_impressions
bình luận bình luận
lượt không thích lượt không thích
thu nhập estimated_partner_revenue
estimatedMinutesWatched watch_time_minutes
estimatedPartnerAdSenseRevenue estimated_partner_adsense_revenue
estimatedPartnerDoubleClickRevenue estimated_partner_doubleclick_revenue
grossRevenue estimated_youtube_ad_revenue
impressionBasedCpm estimated_cpm
lượt hiển thị ad_impressions
lượt thích lượt thích
monetizedPlaybacks estimated_monetized_playbacks
playbackBasedCpm estimated_playback_based_cpm
playlistStarts playlist_starts
savesAdded playlist_saves_added
savesRemoved playlist_saves_removed
phần sở hữu phần sở hữu
subscribersGained subscribers_gained
subscribersLost subscribers_lost
videosAddedToPlaylists videos_added_to_playlists
videosRemovedFromPlaylists videos_removed_from_playlist
viewerPercentage views_percentage
chế độ xem chế độ xem