Reports: Query

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

Lưu ý: Chỉ những đối tác nội dung tham gia Chương trình Đối tác YouTube mới có thể truy cập báo cáo 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ả các yêu cầu API của 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ã thông báo uỷ quyền.

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

Kính ngắm
https://www.googleapis.com/auth/yt-analytics.readonly Xem báo cáo Analytics trên YouTube dành cho nội dung YouTube của bạn. Phạm vi này cung cấp quyền truy cập vào chỉ số hoạt động của người dùng, như số lượt xem và số lượng 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 YouTube của bạn. 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 cũng như các chỉ số ước tính về doanh thu và hiệu suất quảng cáo.
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 YouTube Analytics.
https://www.googleapis.com/auth/youtubepartner Xem và quản lý nội dung YouTube cũng như nội dung được kết hợp 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à mục trong YouTube Analytics.

Các tham số

Các bảng sau liệt kê các tham số truy vấn bắt buộc và không bắt buộc cho 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 là không bắt buộc và được nhiều API của Google hỗ trợ.

Các tham số
Các thông 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 API chứa dữ liệu cho đến ngày cuối cùng của 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ả 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 xảy ra ngay cả khi có sẵn dữ liệu cho một số chỉ số được yêu cầu vào ngày 4 tháng 7 năm 2017.)
Lưu ý: Trong phiên bản 1 của API này, thông số này có 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 sẽ xác định kênh YouTube của người dùng hiện đã được xác thực.
  • Để yêu cầu dữ liệu cho chủ sở hữu nội dung YouTube, hãy đặt giá trị thông số ids thành contentOwner==OWNER_NAME, trong đó OWNER_NAMEcontent owner ID cho người dùng.

metrics string
Danh sách 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 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à các chỉ số có trong mỗi báo cáo. (Tài liệu về Chỉ số chứa định nghĩa cho tất cả các 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 này, thông số này có tên là start-date.
Các thông số không bắt buộc
currency string
Đơn vị tiền tệ mà API này sẽ sử dụng để chỉ định các chỉ số doanh thu ước tính như sau: estimatedDoanh thu ước tính, estimatedAdRevenue, estimatedRedPartner kính, tổng doanh thu, cpm, playbackBasedCpm. Giá trị mà API trả về cho các chỉ số đó được ước tính bằng cách sử dụng tỷ giá hối đoái thay đổi hằng ngày. Nếu không có chỉ số nào trong số này đượ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 ISO 4217, trong danh sách đơ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 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 được sử dụng cho các báo cáo đó. (Tài liệu về Phương diện chứa định nghĩa cho tất cả phương diện.)
filters string
Danh sách các bộ lọc sẽ áp dụng khi truy xuất dữ liệu YouTube Analytics. Tài liệu về báo cáo kênhbáo cáo chủ sở hữu nội dung xác định phương diện có thể dùng để lọc từng báo cáo, còn tài liệu 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 các phương diện đó với dấu chấm phẩy (;) và bảng kết quả được trả về sẽ đáp ứng cả hai bộ lọc. Ví dụ: Giá trị tham số filters của video==dMH0bHeiRNg;country==IT hạn chế kết quả được đặt để bao gồm dữ liệu cho video nhất định tại Ý.

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

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

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ử 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 kênh, trong đó tổng hợp các số liệu thống kê về lượt xem dựa trên cách người xem tiếp cận nội dung video của kênh. Ngoài ra, giả sử yêu cầu tham số filters của yêu cầu xác định danh sách 10 video mà dữ liệu sẽ được trả về.
  • Nếu bạn thêm video vào giá trị của thông số dimensions, phản hồi API sẽ cung cấp số liệu thống kê riêng về nguồn lưu lượng truy cập 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, phản hồi API sẽ tổng hợp số liệu thống kê về nguồn lưu lượng truy cập cho tất cả 10 video.
includeHistoricalChannelData boolean
Lưu ý: Thông số này chỉ áp dụng cho báo cáo chủ sở hữu nội dung.

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

Điều quan trọng cần nhớ là có thể các kênh khác nhau đã liên kết với một chủ sở hữu nội dung vào các 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 API sẽ chứa dữ liệu dựa trên ngày liên kết của từng kênh tương ứng. Nếu giá trị tham số là true, thì phản hồi 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 này, thông số này có tên là include-historical-channel-data.
maxResults integer
Số hàng tối đa cần đưa vào phản hồi.
Lưu ý: Trong phiên bản 1 của API này, thông số này có tên là max-results.
sort string
Danh sách các 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 cho dữ liệu trong YouTube Analytics. Theo mặc định, thứ tự sắp xếp sẽ tăng dần. Tiền tố - gây ra thứ tự sắp xếp giảm dần.
startIndex integer
Chỉ mục 1 dựa trên thực thể đầu tiên cần truy xuất. (Giá trị mặc định là 1.) Sử dụng thông số này làm cơ chế phân trang cùng với thông số max-results.
Lưu ý: Trong phiên bản 1 của API này, thông số này có 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.
  • Một cách để cung cấp mã thông báo OAuth 2.0.
alt Thông 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 gọi lại.
  • Tên của hàm callback JavaScript xử lý phản hồi.
  • Được dùng trong các yêu cầu JSON-P JavaScript.
prettyPrint

Trả về phản hồi bằng thụt lề và ngắt dòng.

  • Trả về phản hồi ở định dạng mà con người có thể đọc được nếu true.
  • Giá trị mặc định: true.
  • Khi giá trị này là false thì có thể làm giảm dung lượng tải trọng phản hồi, giúp cải thiện hiệu suất trong một số môi trường.
quotaUser Thông số này đã được hỗ trợ trong phiên bản 1 của API này (hiện không được dùng nữa). Thông số này không được hỗ trợ trong phiên bản 2 của API này.
userIp Thông số này đã được hỗ trợ trong phiên bản 1 của API này (hiện không được dùng nữa). Thông số này không được hỗ trợ trong phiên bản 2 của API này.

Nội dung yêu cầu

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

Phản hồi

Như đã lưu ý trong đị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 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 API của 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 các 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 đó có 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 các 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ả hai thứ nguyê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 thông số dimensions=ageGroup,gender&metrics=viewerPercentage, phản hồi 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 cá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ó sẵn dữ liệu cho truy vấn đã cho, phần tử rows sẽ bị bỏ qua trong phản hồi.

Phản hồi cho truy vấn có phương diện day sẽ không chứa các 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 ý: Những mã mẫu sau đây có thể không đại diện cho một số 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 số lượt xem hằng ngày và các chỉ số khác cho kênh của người dùng được ủy quyền trong năm dương lịch 2017. Mẫu này sử dụng thư viện ứng dụng JavaScript của API Google.

Trước khi chạy mẫu này lần đầu, bạn cần thiết lập thông tin đăng nhập 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 bạn chưa đặt, rồi 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 cho phép, hãy nhập URL nơi bạn sẽ phân phát mã mẫu. Ví dụ: bạn có thể sử dụng một số tên như 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 quá trình tạo thông tin xác thực.
  8. Trước khi đóng hộp thoại, hãy sao chép mã ứng dụng mà bạn cần đặt vào mã mẫu.

Sau đó, hãy 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 mã ứng dụng khách mà bạn đã nhận được khi thiết lập thông tin uỷ quyền.

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

Bây giờ, bạn đã sẵn sàng để thử nghiệm 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 để chạy luồng uỷ quyền người dùng. Nếu bạn cho phép ứng dụng truy xuất dữ liệu kênh của mình, bạn sẽ thấy các dòng sau in ra bảng điều khiển trong 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 ủy quyền mà bạn đã thiết lập cho dự án của mình và bạn đặt mã ứng dụng khách vào mã như mô tả ở trên.
  4. Nhấp vào nút execute để thực hiện lệnh gọi API. Bạn sẽ thấy một bản in đối tượng response trong bảng điều khiển trong trình duyệt. Trong đối tượng đó, thuộc tính result liên kết 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>

Python

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

Trước khi chạy mẫu này lần đầu, bạn cần thiết lập thông tin đăng nhập 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 bạn chưa đặt, rồi 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, nhập tên "API bắt đầu nhanh của YouTube Analytics" và nhấp vào nút Tạo.
  6. Nhấp vào OK để đóng hộp thoại xuất hiện.
  7. Nhấp vào nút (Tải xuống JSON) ở bên phải mã ứng dụng khách.
  8. Di chuyển tệp đã tải xuống sang thư mục đang hoạt động của bạn.

Bạn cũng cần cài đặt Thư viện ứng dụng Python cho API của Google 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 để thử nghiệm mẫu:

  1. Sao chép mã mẫu dưới đây vào thư mục đang hoạt động 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 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 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 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ể phải sao chép URL xác thực vào một cửa sổ trình duyệt. Khi kết thúc quy trình uỷ quyền, nếu cần, hãy dán mã uỷ quyền xuất hiện trong trình duyệt vào cửa sổ dòng lệnh rồi nhấp vào [return].
  5. Truy vấn API thực thi và phản hồi JSON được xuất sang 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'
  )

Hãy dùng thử!

Hãy 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.