YouTube Reporting API - System-Managed Reports

YouTube tự động tạo một nhóm báo cáo doanh thu từ quảng 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 Creator Studio. Các báo cáo này được thiết kế để cung cấp quyền truy cập có lập trình vào dữ liệu có sẵn trong báo cáo có thể tải xuống theo cách thủ công. Bạn có thể truy cập vào các báo cáo này trong trình đơn Báo cáo của YouTube Studio.

Lưu ý: API cấp quyền truy cập vào tập hợp báo cáo khác với Creator Studio, mặc dù các báo cáo chứa dữ liệu tương tự. Báo cáo API có thể có các trường khác nhau và cũng sử dụng các tên trường khác với báo cáo Creator Studio.

Vì YouTube tự động tạo báo cáo do hệ thống quản lý nên quy trình truy xuất những báo cáo này sẽ khác với quy trình truy xuất dữ liệu hàng loạt trong YouTube Analytics được cung cấp thông qua API.

Truy xuất báo cáo

Các bước sau giải thích cách truy xuất báo cáo do hệ thống quản lý qua API.

Bước 1: Truy xuất thông tin xác thực uỷ quyền

Tất cả các yêu cầu liên quan đến API Báo cáo của YouTube đề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.

Các yêu cầu API Báo cáo của YouTube sử dụng những phạm vi uỷ quyền sau:

Phạm vi
https://www.googleapis.com/auth/yt-analytics.readonly Xem các báo cáo trong 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 trong YouTube Analytics 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, cũng như doanh thu ước tính và các chỉ số hiệu suất quảng cáo.

Bước 2: Truy xuất mã công việc cho báo cáo mong muốn

Gọi phương thức jobs.list để truy xuất danh sách công việc do hệ thống quản lý. Đặt tham số includeSystemManaged thành true.

Thuộc tính reportTypeId trong mỗi tài nguyên Job được trả về sẽ xác định loại báo cáo do hệ thống quản lý liên kết với công việc đó. Ứng dụng của bạn cần giá trị thuộc tính id từ cùng một tài nguyên trong bước sau.

Tài liệu Báo cáo liệt kê các báo cáo có sẵn, mã loại báo cáo và các trường trong báo cáo. Bạn cũng có thể sử dụng phương thức reportTypes.list để truy xuất danh sách các loại báo cáo được hỗ trợ.

Bước 3: Truy xuất URL tải xuống của báo cáo

Gọi phương thức jobs.reports.list để truy xuất danh sách báo cáo được tạo cho công việc đó. Trong yêu cầu, hãy đặt tham số jobId thành mã công việc của báo cáo mà bạn muốn truy xuất.

Bạn có thể lọc danh sách báo cáo bằng bất kỳ hoặc tất cả các thông số sau:

  • Sử dụng tham số createdAfter để cho biết rằng API chỉ nên trả về các báo cáo được tạo sau một thời gian cụ thể. Bạn có thể dùng thông số này để đảm bảo rằng API chỉ trả về những báo cáo mà bạn chưa xử lý.

  • Sử dụng tham số startTimeBefore để cho biết rằng phản hồi của API chỉ nên chứa báo cáo nếu dữ liệu sớm nhất trong báo cáo có trước ngày đã chỉ định. Trong khi thông số createdAfter liên quan đến thời gian tạo báo cáo, thì ngày này liên quan đến dữ liệu trong báo cáo.

  • Sử dụng tham số startTimeAtOrAfter để cho biết rằng phản hồi của API chỉ nên chứa báo cáo nếu dữ liệu cũ nhất trong báo cáo vào hoặc sau ngày đã chỉ định. Giống như thông số startTimeBefore, giá trị thông số này tương ứng với dữ liệu trong báo cáo chứ không phải với thời gian báo cáo được tạo.

Phản hồi của API chứa danh sách các tài nguyên Report dành cho công việc đó. Mỗi tài nguyên tương ứng với một báo cáo chứa dữ liệu trong một khoảng thời gian riêng biệt.

  • Các thuộc tính startTime và endTime của tài nguyên xác định khoảng thời gian mà dữ liệu của báo cáo đề cập đến.
  • Thuộc tính downloadUrl của tài nguyên xác định URL có thể tìm nạp báo cáo.

  • Thuộc tính createTime của tài nguyên chỉ định ngày và giờ tạo báo cáo. Ứng dụng của bạn nên lưu trữ giá trị này và sử dụng giá trị này để xác định xem các báo cáo đã tải xuống trước đó có thay đổi hay không.

Bước 4: Tải báo cáo xuống

Gửi yêu cầu GET HTTP đến downloadUrl nhận được ở bước 4 để truy xuất báo cáo.

Đang xử lý báo cáo

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

Các ứng dụng sử dụng API Báo cáo YouTube phải luôn tuân thủ các phương pháp sau:

  • Sử dụng hàng tiêu đề của báo cáo để xác định thứ tự các cột của báo cáo. Ví dụ: đừng giả định rằng số lượt xem sẽ là chỉ số đầu tiên được trả về trong một báo cáo 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 báo cáo để xác định cột nào chứa dữ liệu đó.

  • Lưu giữ bản ghi của các báo cáo bạn đã tải xuống để tránh xử lý nhiều lần cùng một báo cáo. Danh sách sau đây đề xuất một số cách để thực hiện việc này.

    • Khi gọi phương thức reports.list, hãy sử dụng tham số createdAfter để chỉ truy xuất các báo cáo được tạo sau một ngày nhất định. (Hãy bỏ qua tham số createdAfter trong lần đầu tiên bạn truy xuất báo cáo.)

      Mỗi lần bạn truy xuất và xử lý báo cáo thành công, hãy lưu trữ dấu thời gian tương ứng với ngày và giờ khi báo cáo mới nhất được tạo. Sau đó, hãy cập nhật giá trị tham số createdAfter trong mỗi lệnh gọi liên tiếp tới phương thức reports.list để đảm bảo rằng bạn chỉ truy xuất các báo cáo mới, bao gồm cả các báo cáo mới có dữ liệu được bổ sung, mỗi khi bạn gọi API.

      Để bảo vệ, trước khi truy xuất một báo cáo, bạn cũng nên kiểm tra để đảm bảo rằng mã nhận dạng của báo cáo đó chưa có trong cơ sở dữ liệu của bạn.

    • Lưu trữ mã nhận dạng cho mỗi báo cáo mà bạn đã tải xuống và xử lý. Bạn cũng có thể lưu trữ các thông tin bổ sung như ngày và giờ mà mỗi báo cáo được tạo hoặc startTime và endTime của báo cáo. Những thông tin này cùng xác định khoảng thời gian mà báo cáo chứa dữ liệu. Đối với những báo cáo truy xuất dữ liệu hàng loạt cho YouTube Analytics, mỗi công việc có thể sẽ có nhiều báo cáo vì mỗi báo cáo đều chứa dữ liệu trong khoảng thời gian 24 giờ. Công việc do hệ thống quản lý trong khoảng thời gian dài hơn sẽ có ít báo cáo hơn.

      Sử dụng mã báo cáo để xác định những báo cáo mà bạn vẫn cần tải xuống và nhập. Tuy nhiên, nếu hai báo cáo mới có cùng giá trị thuộc tính startTime và endTime, thì bạn chỉ cần nhập báo cáo có giá trị createTime mới hơn.

Đặc điểm của báo cáo

Báo cáo API là các tệp .csv được tạo phiên bản (giá trị được phân tách bằng dấu phẩy) có các đặc điểm sau:

  • Mỗi báo cáo chứa dữ liệu cho một khoảng thời gian riêng biệt kéo dài từ 12:00 sáng (theo giờ Thái Bình Dương) vào ngày bắt đầu báo cáo đến 11:59 đêm (giờ Thái Bình Dương) vào ngày kết thúc báo cáo.

  • Dữ liệu báo cáo không được sắp xếp.