Reports: Query

Lưu ý quan trọng: Các yêu cầu API đối với phương thức này hiện đòi hỏi quyền truy cập vào phạm vi https://www.googleapis.com/auth/youtube.readonly.

Phương pháp này cho phép bạn truy xuất nhiều báo cáo Analytics khác nhau. Mỗi yêu cầu sử dụng tham số truy vấn để chỉ định mã nhận dạng kênh hoặc chủ sở hữu nội dung, ngày bắt đầu, ngày kết thúc và ít nhất một chỉ số. Bạn cũng có thể cung cấp thêm tham số truy vấn, chẳng hạn như phương diện, bộ lọc và hướng dẫn sắp xếp.

  • Chỉ số là các chỉ số đo lường riêng lẻ về hoạt động của người dùng, chẳng hạn như lượt xem video hoặc điểm xếp hạng (lượt thích và lượt không thích).
  • 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.
  • Bộ lọc là các giá trị phương diện chỉ định dữ liệu cần truy xuất. Ví dụ: bạn có thể truy xuất dữ liệu cho một quốc gia, một video cụ thể hoặc một nhóm video.

Lưu ý: Chỉ những đối tác nội dung của YouTube tham gia Chương trình Đối tác YouTube mới có thể truy cập vào báo cáo của chủ sở hữu nội dung.

Các trường hợp sử dụng phổ biến

Yêu cầu

Yêu cầu HTTP

GET https://youtubeanalytics.googleapis.com/v2/reports

Tất cả yêu cầu API YouTube Analytics đều phải được cho phép. Hướng dẫn uỷ quyền giải thích cách sử dụng giao thức OAuth 2.0 để truy xuất mã uỷ quyền.

Yêu cầu API YouTube Analytics sử dụng các phạm vi uỷ quyền sau:

Phạm vi
https://www.googleapis.com/auth/yt-analytics.readonly Xem báo cáo YouTube Analytics dành cho nội dung của bạn trên YouTube. Phạm vi này cung cấp quyền truy cập vào các chỉ số hoạt động của người dùng, chẳng hạn như số lượt xem và số lượt xếp hạng.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Xem báo cáo tiền trên YouTube Analytics cho nội dung trên YouTube của bạn. Phạm vi này cấp quyền truy cập vào các chỉ số về hoạt động của người dùng, cũng như các chỉ số về doanh thu và hiệu suất quảng cáo ước tính.
https://www.googleapis.com/auth/youtube Quản lý tài khoản YouTube của bạn. Trong API YouTube Analytics, chủ sở hữu kênh sử dụng phạm vi này để quản lý các nhóm và mục trong nhóm trong YouTube Analytics.
https://www.googleapis.com/auth/youtubepartner Xem và quản lý tài sản và nội dung liên quan trên YouTube. Trong API YouTube Analytics, chủ sở hữu nội dung sử dụng phạm vi này để quản lý các nhóm và các mục trong nhóm trong YouTube Analytics.

Tham số

Bảng sau đây liệt kê các tham số truy vấn bắt buộc và không bắt buộc đối với các yêu cầu API để truy xuất báo cáo truy vấn. Các tham số truy vấn chuẩn được liệt kê trong bảng cũng không bắt buộc và được nhiều API của Google hỗ trợ.

Tham số
Tham số bắt buộc
endDate string
Ngày kết thúc tìm nạp dữ liệu YouTube Analytics. Giá trị phải ở định dạng YYYY-MM-DD.

Phản hồi của API chứa dữ liệu tính đến ngày cuối cùng mà tất cả các chỉ số trong truy vấn có sẵn tại thời điểm truy vấn. Ví dụ: nếu yêu cầu chỉ định ngày kết thúc là ngày 5 tháng 7 năm 2017 và giá trị cho tất cả các chỉ số được yêu cầu chỉ có sẵn đến hết ngày 3 tháng 7 năm 2017, thì đó sẽ là ngày cuối cùng mà dữ liệu được đưa vào phản hồi. (Điều này vẫn đúng ngay cả khi dữ liệu cho một số chỉ số được yêu cầu có sẵn cho ngày 4 tháng 7 năm 2017.)
Lưu ý: Trong phiên bản 1 của API, tham số này được đặt tên là end-date.
ids string
Xác định kênh YouTube hoặc chủ sở hữu nội dung mà bạn đang truy xuất dữ liệu YouTube Analytics.

  • Để yêu cầu dữ liệu cho một kênh YouTube, hãy đặt giá trị tham số ids thành channel==MINE hoặc channel==CHANNEL_ID, trong đó CHANNEL_ID xác định kênh YouTube của người dùng hiện đã xác thực.
  • Để yêu cầu dữ liệu cho một chủ sở hữu nội dung trên YouTube, hãy đặt giá trị thông số ids thành contentOwner==OWNER_NAME, trong đó OWNER_NAME là content owner ID cho người dùng.

metrics string
Một danh sách gồm các chỉ số YouTube Analytics được phân tách bằng dấu phẩy, chẳng hạn như views hoặc likes,dislikes. Hãy xem tài liệu về báo cáo kênh hoặc báo cáo của chủ sở hữu nội dung để biết danh sách báo cáo mà bạn có thể truy xuất và chỉ số có trong mỗi báo cáo. (Tài liệu về Chỉ số trình bày định nghĩa cho mọi chỉ số.)
startDate string
Ngày bắt đầu tìm nạp dữ liệu YouTube Analytics. Giá trị phải ở định dạng YYYY-MM-DD.
Lưu ý: Trong phiên bản 1 của API, tham số này được đặt tên là start-date.
Thông số không bắt buộc
currency string
Đơn vị tiền tệ mà API sẽ sử dụng để chỉ định các chỉ số doanh thu ước tính sau đây: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, playbackBasedCpm. Các giá trị mà API trả về cho các chỉ số đó là giá trị ước tính được tính theo tỷ giá hối đoái thay đổi hằng ngày. Nếu không có chỉ số nào trong số đó được yêu cầu, thì thông số này sẽ bị bỏ qua.

Giá trị thông số là mã đơn vị tiền tệ gồm ba chữ cái theo tiêu chuẩn ISO 4217 trong danh sách các đơn vị tiền tệ dưới đây. API sẽ trả về lỗi nếu bạn chỉ định đơn vị tiền tệ không được hỗ trợ. Giá trị mặc định là USD.
dimensions string
Danh sách các phương diện YouTube Analytics được phân tách bằng dấu phẩy, chẳng hạn như video hoặc ageGroup,gender. Hãy xem tài liệu về báo cáo kênh hoặc báo cáo của chủ sở hữu nội dung để biết danh sách báo cáo mà bạn có thể truy xuất và phương diện dùng cho những báo cáo đó. (Tài liệu về Phương diện chứa định nghĩa cho tất cả các phương diện.)
filters string
Danh sách các bộ lọc nên được áp dụng khi truy xuất dữ liệu YouTube Analytics. Tài liệu về báo cáo kênh và báo cáo của chủ sở hữu nội dung xác định các phương diện có thể dùng để lọc từng báo cáo, và tài liệu về Phương diện xác định các phương diện đó.

Nếu một yêu cầu sử dụng nhiều bộ lọc, hãy kết hợp chúng cùng với dấu chấm phẩy (;) và bảng kết quả trả về sẽ đáp ứng cả hai bộ lọc. Ví dụ: giá trị tham số filters là video==dMH0bHeiRNg;country==IT giới hạn tập hợp kết quả để bao gồm dữ liệu của video cụ thể ở Ý.

Chỉ định nhiều giá trị cho một bộ lọc

API này hỗ trợ khả năng chỉ định nhiều giá trị cho các bộ lọc video, playlist và channel. Để thực hiện việc này, hãy chỉ định một danh sách riêng biệt gồm video, danh sách phát hoặc mã nhận dạng kênh cần lọc phản hồi API. Ví dụ: giá trị tham số filters là video==pd1FJh59zxQ,Zhawgd0REhA;country==IT giới hạn tập hợp kết quả để bao gồm dữ liệu cho các video cụ thể ở Ý. Giá trị thông số có thể chỉ định tối đa 500 mã nhận dạng.

Khi chỉ định nhiều giá trị cho cùng một bộ lọc, bạn cũng có thể thêm bộ lọc đó vào danh sách phương diện mà bạn chỉ định cho yêu cầu. Điều này đúng ngay cả khi bộ lọc không được liệt kê là phương diện được hỗ trợ cho một báo cáo cụ thể. Nếu bạn thêm bộ lọc vào danh sách phương diện, thì API cũng sẽ sử dụng các giá trị bộ lọc để nhóm kết quả.

Ví dụ: Giả sử bạn truy xuất báo cáo nguồn lưu lượng truy cập của một kênh, trong đó tổng hợp số liệu thống kê về lượt xem dựa trên cách thức người xem truy cập vào nội dung video của kênh đó. Giả sử yêu cầu tham số filters của yêu cầu xác định một danh sách gồm 10 video cần trả về dữ liệu.
  • Nếu bạn thêm video vào giá trị của tham số dimensions, thì phản hồi của API sẽ cung cấp số liệu thống kê về nguồn lưu lượng truy cập riêng cho từng video trong số 10 video.
  • Nếu bạn không thêm video vào giá trị của tham số dimensions thì phản hồi của API sẽ tổng hợp số liệu thống kê về nguồn lưu lượng truy cập của tất cả 10 video.
includeHistoricalChannelData boolean
Lưu ý: Tham số này chỉ áp dụng cho báo cáo của chủ sở hữu nội dung.

Cho biết liệu phản hồi của API có bao gồm thời gian xem của kênh và dữ liệu lượt xem trong khoảng thời gian trước thời điểm kênh được liên kết với chủ sở hữu nội dung hay không. Giá trị tham số mặc định là false, tức là phản hồi của API chỉ bao gồm dữ liệu về thời gian xem và lượt xem từ những ngày mà kênh liên kết với chủ sở hữu nội dung.

Bạn cần nhớ là có thể các kênh khác nhau đã được liên kết với một chủ sở hữu nội dung vào những ngày khác nhau. Nếu yêu cầu API đang truy xuất dữ liệu cho nhiều kênh và giá trị tham số là false, thì phản hồi của API chứa dữ liệu dựa trên ngày liên kết cho từng kênh tương ứng. Nếu giá trị tham số là true, thì phản hồi của API sẽ chứa dữ liệu khớp với ngày được chỉ định trong yêu cầu API.
Lưu ý: Trong phiên bản 1 của API, tham số này được đặt tên là include-historical-channel-data.
maxResults integer
Số hàng tối đa có thể đưa vào phản hồi.
Lưu ý: Trong phiên bản 1 của API, tham số này được đặt tên là max-results.
sort string
Danh sách phương diện hoặc chỉ số được phân tách bằng dấu phẩy giúp xác định thứ tự sắp xếp dữ liệu trong YouTube Analytics. Theo mặc định, thứ tự sắp xếp là tăng dần. Tiền tố - tạo ra thứ tự sắp xếp giảm dần.
startIndex integer
Chỉ mục dựa trên 1 của thực thể đầu tiên cần truy xuất. (Giá trị mặc định là 1.) Hãy dùng tham số này làm cơ chế phân trang cùng với tham số max-results.
Lưu ý: Trong phiên bản 1 của API, tham số này được đặt tên là start-index.
Tham số chuẩn
access_token Mã thông báo OAuth 2.0 cho người dùng hiện tại.
alt Tham số này không được hỗ trợ trong phiên bản 2 của API, chỉ hỗ trợ phản hồi JSON.Định dạng dữ liệu cho phản hồi API.
  • Giá trị hợp lệ: json, csv
  • Giá trị mặc định: json
callback Hàm callback.
  • Tên của hàm callback JavaScript xử lý phản hồi.
  • Được dùng trong các yêu cầu JavaScript JSON-P.
prettyPrint

Trả về phản hồi có thụt đầu dòng và ngắt dòng.

  • Trả về phản hồi ở định dạng con người có thể đọc được nếu true.
  • Giá trị mặc định: true.
  • Khi giá trị này là false, phương thức này có thể giảm kích thước tải trọng phản hồi, nhờ đó có thể nâng cao hiệu suất trong một số môi trường.
quotaUser Tham số này được hỗ trợ trong phiên bản 1 của API nhưng hiện không còn dùng nữa. Tham số này không được hỗ trợ trong phiên bản 2 của API.
userIp Tham số này được hỗ trợ trong phiên bản 1 của API nhưng hiện không còn dùng nữa. Tham số này không được hỗ trợ trong phiên bản 2 của API.

Nội dung yêu cầu

Đừng gửi nội dung yêu cầu khi gọi phương thức này.

Phản hồi

Như đã nêu trong phần định nghĩa tham số alt, API có thể trả về phản hồi ở định dạng JSON hoặc CSV. Dưới đây là thông tin về nội dung phản hồi cho từng loại:

JSON
{
  "kind": "youtubeAnalytics#resultTable",
  "columnHeaders": [
    {
      "name": string,
      "dataType": string,
      "columnType": string
    },
    ... more headers ...
  ],
  "rows": [
    [
      {value}, {value}, ...
    ]
  ]
}
Thuộc tính
kind string
Giá trị này chỉ định loại dữ liệu có trong phản hồi của API. Đối với phương thức query, giá trị thuộc tính kind sẽ là youtubeAnalytics#resultTable. Tuy nhiên, nếu API hỗ trợ thêm các phương thức khác, thì phản hồi của API cho các phương thức đó có thể giới thiệu các giá trị thuộc tính kind khác.
columnHeaders[] list
Giá trị này chỉ định thông tin về dữ liệu được trả về trong trường rows. Mỗi mục trong danh sách columnHeaders xác định một trường được trả về trong giá trị rows, trong đó chứa danh sách dữ liệu được phân tách bằng dấu phẩy.

Danh sách columnHeaders bắt đầu bằng phương diện được chỉ định trong yêu cầu API, theo sau là các chỉ số được chỉ định trong yêu cầu API. Thứ tự của cả phương diện và chỉ số khớp với thứ tự trong yêu cầu API.

Ví dụ: nếu yêu cầu API chứa các tham số dimensions=ageGroup,gender&metrics=viewerPercentage, thì phản hồi của API sẽ trả về các cột theo thứ tự sau: ageGroup,gender,viewerPercentage.
columnHeaders[].name string
Tên của phương diện hoặc chỉ số.
columnHeaders[].columnType string
Loại cột (DIMENSION hoặc METRIC).
columnHeaders[].dataType string
Loại dữ liệu trong cột (STRING, INTEGER, FLOAT, v.v.).
rows[] list
Danh sách này chứa tất cả các hàng của bảng kết quả. Mỗi mục trong danh sách là một mảng chứa dữ liệu được phân tách bằng dấu phẩy tương ứng với một hàng dữ liệu. Thứ tự của các trường dữ liệu được phân tách bằng dấu phẩy sẽ khớp với thứ tự của các cột được liệt kê trong trường columnHeaders.

Nếu không có dữ liệu cho truy vấn đã cho, phần tử rows sẽ bị loại khỏi phản hồi.

Phản hồi cho truy vấn có phương diện day sẽ không chứa hàng cho những ngày gần đây nhất.

CSV
day, views, likes, ...
"2012-01-01", 12.0, 3, ...
"2012-01-02", 16.0, 2, ...
"2012-01-03", 18.0, 8, ...
...

Ví dụ

Lưu ý: Các mã mẫu sau đây có thể không đại diện cho tất cả ngôn ngữ lập trình được hỗ trợ. Xem tài liệu về thư viện ứng dụng để biết danh sách các ngôn ngữ được hỗ trợ.

JavaScript

Ví dụ này gọi API YouTube Analytics để truy xuất lượt xem hằng ngày và các chỉ số khác cho việc cấp quyền cho kênh của người dùng trong năm dương lịch 2017. Mẫu này sử dụng thư viện ứng dụng JavaScript API của Google.

Trước khi chạy mẫu này trên máy lần đầu tiên, bạn cần thiết lập thông tin xác thực uỷ quyền cho dự án của mình:
  1. Tạo hoặc chọn một dự án trong Google API Console.
  2. Bật API YouTube Analytics cho dự án của bạn.
  3. Ở đầu trang Thông tin xác thực, hãy chọn thẻ màn hình xin phép bằng OAuth. Chọn một địa chỉ email, nhập Tên sản phẩm (nếu chưa đặt) và nhấp vào nút Lưu.
  4. Trên trang Thông tin xác thực, hãy nhấp vào nút Tạo thông tin xác thực rồi chọn Mã ứng dụng khách Oauth.
  5. Chọn loại ứng dụng Ứng dụng web.
  6. Trong trường Nguồn gốc JavaScript được uỷ quyền, hãy nhập URL mà bạn sẽ phân phát mã mẫu từ đó. Ví dụ: bạn có thể sử dụng tên http://localhost:8000 hoặc http://yourserver.example.com. Bạn có thể để trống trường URI chuyển hướng được uỷ quyền.
  7. Nhấp vào nút Tạo để hoàn tất việc tạo thông tin đăng nhập.
  8. Trước khi đóng hộp thoại, hãy sao chép mã ứng dụng khách mà bạn cần đưa vào mã mẫu.

Sau đó, lưu mẫu vào một tệp cục bộ. Trong mẫu này, hãy tìm dòng sau và thay thế YOUR_CLIENT_ID bằng ID ứng dụng khách mà bạn nhận được khi thiết lập thông tin xác thực ủy quyền.

gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});

Bây giờ, bạn đã sẵn sàng kiểm thử thực tế mẫu:

  1. Mở tệp cục bộ từ trình duyệt web và mở bảng điều khiển gỡ lỗi trong trình duyệt. Bạn sẽ thấy một trang hiển thị hai nút.
  2. Nhấp vào nút uỷ quyền và tải để khởi chạy quy trình cấp phép cho người dùng. Nếu cho phép ứng dụng này truy xuất dữ liệu kênh của bạn, bạn sẽ thấy các dòng sau xuất hiện trong bảng điều khiển trên trình duyệt: 
    Sign-in successful
GAPI client loaded for API
  3. Nếu bạn thấy thông báo lỗi thay vì các dòng ở trên, hãy xác nhận rằng bạn đang tải tập lệnh từ URI chuyển hướng được uỷ quyền mà bạn đã thiết lập cho dự án của mình và bạn đã đặt ID ứng dụng khách vào mã như được mô tả ở trên.
  4. Nhấp vào nút execute để gọi API. Bạn sẽ thấy một đối tượng response in ra bảng điều khiển trong trình duyệt. Trong đối tượng đó, thuộc tính result ánh xạ tới một đối tượng chứa dữ liệu API.
<script src="https://apis.google.com/js/api.js"></script>
<script>
  function authenticate() {
    return gapi.auth2.getAuthInstance()
        .signIn({scope: "https://www.googleapis.com/auth/yt-analytics.readonly"})
        .then(function() { console.log("Sign-in successful"); },
              function(err) { console.error("Error signing in", err); });
  }
  function loadClient() {
    return gapi.client.load("https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2")
        .then(function() { console.log("GAPI client loaded for API"); },
              function(err) { console.error("Error loading GAPI client for API", err); });
  }
  // Make sure the client is loaded and sign-in is complete before calling this method.
  function execute() {
    return gapi.client.youtubeAnalytics.reports.query({
      "ids": "channel==MINE",
      "startDate": "2017-01-01",
      "endDate": "2017-12-31",
      "metrics": "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained",
      "dimensions": "day",
      "sort": "day"
    })
        .then(function(response) {
                // Handle the results here (response.result has the parsed body).
                console.log("Response", response);
              },
              function(err) { console.error("Execute error", err); });
  }
  gapi.load("client:auth2", function() {
    gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
  });
</script>
<button onclick="authenticate().then(loadClient)">authorize and load</button>
<button onclick="execute()">execute</button>

yt_analytics_v2.html

Python

Ví dụ này gọi API YouTube Analytics để truy xuất lượt xem hằng ngày và các chỉ số khác cho việc cấp quyền cho kênh của người dùng trong năm dương lịch 2017. Mẫu này sử dụng thư viện ứng dụng Google API Python.

Trước khi chạy mẫu này trên máy lần đầu tiên, bạn cần thiết lập thông tin xác thực uỷ quyền cho dự án của mình:
  1. Tạo hoặc chọn một dự án trong Google API Console.
  2. Bật API YouTube Analytics cho dự án của bạn.
  3. Ở đầu trang Thông tin xác thực, hãy chọn thẻ màn hình xin phép bằng OAuth. Chọn một địa chỉ email, nhập Tên sản phẩm (nếu chưa đặt) và nhấp vào nút Lưu.
  4. Trên trang Thông tin xác thực, hãy nhấp vào nút Tạo thông tin xác thực rồi chọn Mã ứng dụng khách Oauth.
  5. Chọn loại ứng dụng Khác, sau đó nhập tên "Bắt đầu nhanh API YouTube Analytics" rồi nhấp vào nút Tạo.
  6. Nhấp vào OK để đóng hộp thoại thu được.
  7. Nhấp vào nút (Tải JSON xuống) ở bên phải của mã ứng dụng khách.
  8. Chuyển tệp đã tải xuống vào thư mục đang làm việc.

Bạn cũng cần cài đặt Thư viện ứng dụng API của Google cho Python và một số thư viện khác:

pip install --upgrade google-api-python-client
pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2

Bây giờ, bạn đã sẵn sàng kiểm thử thực tế mẫu:

  1. Sao chép mã mẫu bên dưới vào thư mục đang làm việc của bạn.
  2. Trong mẫu này, hãy cập nhật giá trị của biến CLIENT_SECRETS_FILE sao cho khớp với vị trí của tệp mà bạn đã tải xuống sau khi thiết lập thông tin xác thực uỷ quyền.
  3. Chạy mã mẫu trong cửa sổ dòng lệnh: 
    python yt_analytics_v2.py
  4. Thực hiện các bước trong quy trình uỷ quyền. Quy trình xác thực có thể tự động tải trong trình duyệt của bạn hoặc bạn có thể cần phải sao chép URL xác thực vào một cửa sổ trình duyệt. Vào cuối quy trình uỷ quyền, nếu cần, hãy dán mã uỷ quyền hiển thị trong trình duyệt vào cửa sổ dòng lệnh rồi nhấp vào nút [trả lại].
  5. Truy vấn API sẽ thực thi và phản hồi JSON được xuất ra cửa sổ dòng lệnh.
# -*- coding: utf-8 -*-

import os
import google.oauth2.credentials
import google_auth_oauthlib.flow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly']

API_SERVICE_NAME = 'youtubeAnalytics'
API_VERSION = 'v2'
CLIENT_SECRETS_FILE = 'YOUR_CLIENT_SECRET_FILE.json'
def get_service():
  flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_FILE, SCOPES)
  credentials = flow.run_console()
  return build(API_SERVICE_NAME, API_VERSION, credentials = credentials)

def execute_api_request(client_library_function, **kwargs):
  response = client_library_function(
    **kwargs
  ).execute()

  print(response)

if __name__ == '__main__':
  # Disable OAuthlib's HTTPs verification when running locally.
  # *DO NOT* leave this option enabled when running in production.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  youtubeAnalytics = get_service()
  execute_api_request(
      youtubeAnalytics.reports().query,
      ids='channel==MINE',
      startDate='2017-01-01',
      endDate='2017-12-31',
      metrics='estimatedMinutesWatched,views,likes,subscribersGained'
      dimensions='day',
      sort='day'
  )

yt_analytics_v2.py

Hãy dùng thử!

Dùng APIs Explorer để gọi API này cũng như xem yêu cầu và phản hồi của API.