YouTube Reporting API - Get Bulk Data Reports
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
YouTube tự động tạo một bộ 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 các báo cáo tương ứng trong YouTube Studio. Các báo cáo này được thiết kế để cung cấp quyền truy cập theo chương trình vào dữ liệu có trong các báo cáo có thể tải xuống theo cách thủ công trong trình đơn Báo cáo của YouTube Creator Studio.
Lưu ý: API cung cấp quyền truy cập vào một nhóm báo cáo khác với Creator Studio, mặc dù các báo cáo này 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 tên trường khác với báo cáo trong 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 các báo cáo này sẽ khác với quy trình truy xuất báo cáo dữ liệu hàng loạt của YouTube Analytics thông qua API.
Truy xuất báo cáo
Các bước sau đây giải thích cách truy xuất báo cáo do hệ thống quản lý thông qua API.
Bước 1: Truy xuất thông tin đăng nhập uỷ quyền
Tất cả các yêu cầu gửi đến YouTube Reporting API đề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.
Các yêu cầu gửi đến YouTube Reporting API 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 của YouTube Analytics cho nội dung trên YouTube. Phạm vi này cho phép truy cập vào các chỉ số về hoạt động của người dùng, chẳng hạn như số lượt xem và số lượt đánh giá. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly |
Xem báo cáo của YouTube Analytics về tài chính cho nội dung trên YouTube. Phạm vi này cho phép 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 ước tính và 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ác 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ý được 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 tiếp theo.
Tài liệu Báo cáo liệt kê các báo cáo hiện có, mã loại báo cáo và các trường có 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ã nhận dạng 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 cách sử dụng một 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ề những báo cáo được tạo sau một thời gian cụ thể. Bạn có thể dùng tham 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 API chỉ nên chứa các báo cáo nếu dữ liệu sớm nhất trong báo cáo là trước ngày được chỉ định. Trong khi tham số createdAfter liên quan đến thời điểm 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 API chỉ nên chứa báo cáo nếu dữ liệu sớm nhất trong báo cáo là vào hoặc sau ngày được chỉ định. Giống như tham số startTimeBefore, giá trị tham số này tương ứng với dữ liệu trong báo cáo chứ không phải thời gian tạo báo cáo.
Phản hồi của API chứa danh sách các tài nguyên Report cho công việc đó. Mỗi tài nguyên đề cập đến một báo cáo chứa dữ liệu cho một khoảng thời gian duy nhấ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 mà từ đó 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 phải lưu trữ giá trị này và sử dụng giá trị đó để 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 HTTP GET đến downloadUrl thu được ở bước 4 để truy xuất báo cáo.
Báo cáo xử lý
Các phương pháp hay nhất
Các ứng dụng sử dụng YouTube Reporting API luôn phải tuân thủ những phương pháp sau:
-
Sử dụng hàng tiêu đề của báo cáo để xác định thứ tự của các cột trong báo cáo. Ví dụ: đừng cho rằng 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 chứa dữ liệu đó.
-
Lưu giữ hồ sơ về những báo cáo bạn đã tải xuống để tránh xử lý cùng một báo cáo nhiều lần. Danh sách sau đây đề xuất một số cách để thực hiện việc đó.
-
Khi gọi phương thức reports.list, hãy sử dụng tham số createdAfter để chỉ truy xuất những báo cáo được tạo sau một ngày nhất định. (Bỏ qua tham số createdAfter vào 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ý thành công báo cáo, 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 trong số đó được tạo. Sau đó, hãy cập nhật giá trị tham số createdAfter trong mỗi lần gọi liên tiếp đến 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ả báo cáo mới có dữ liệu được điền lại) mỗi khi gọi API.
Để đảm bảo an toàn, trước khi truy xuất một báo cáo, hãy 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 từng báo cáo mà bạn đã tải xuống và xử lý. Bạn cũng có thể lưu trữ thông tin bổ sung như ngày và giờ khi mỗi báo cáo được tạo hoặc startTime và endTime của báo cáo. Hai thông tin này cùng nhau 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 tác vụ có thể có nhiều báo cáo vì mỗi báo cáo chứa dữ liệu trong khoảng thời gian 24 giờ. Các lệnh 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 2 báo cáo mới có cùng giá trị thuộc tính startTime và endTime, thì chỉ 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 (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 cho đến 11:59 tối theo 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.
Trừ phi có lưu ý khác, nội dung của trang này được cấp phép theo Giấy phép ghi nhận tác giả 4.0 của Creative Commons và các mẫu mã lập trình được cấp phép theo Giấy phép Apache 2.0. Để biết thông tin chi tiết, vui lòng tham khảo Chính sách trang web của Google Developers. Java là nhãn hiệu đã đăng ký của Oracle và/hoặc các đơn vị liên kết với Oracle.
Cập nhật lần gần đây nhất: 2025-08-21 UTC.
[null,null,["Cập nhật lần gần đây nhất: 2025-08-21 UTC."],[[["\u003cp\u003eYouTube's Reporting API provides access to system-managed ad revenue reports, which differ from Creator Studio reports in terms of fields and naming, yet contain similar data.\u003c/p\u003e\n"],["\u003cp\u003eRetrieving these reports involves four steps: getting authorization credentials, retrieving the job ID, getting the report's download URL, and downloading the report.\u003c/p\u003e\n"],["\u003cp\u003eThe API requires specific authorization scopes, either \u003ccode\u003ehttps://www.googleapis.com/auth/yt-analytics.readonly\u003c/code\u003e for general user activity metrics or \u003ccode\u003ehttps://www.googleapis.com/auth/yt-analytics-monetary.readonly\u003c/code\u003e for monetary and ad performance metrics.\u003c/p\u003e\n"],["\u003cp\u003eBest practices for using the API include using the header row to identify column ordering and keeping a record of downloaded reports to avoid reprocessing the same data, while also checking for updated reports.\u003c/p\u003e\n"],["\u003cp\u003eEach report is a \u003ccode\u003e.csv\u003c/code\u003e file containing data for a specific period, from 12:00 a.m. to 11:59 p.m. Pacific Time, and the data within the reports is not sorted.\u003c/p\u003e\n"]]],["YouTube provides system-managed ad revenue reports accessible via the Reporting API. To retrieve these reports, first, obtain authorization credentials using OAuth 2.0. Next, retrieve the job ID for the desired report type by calling `jobs.list` with `includeSystemManaged` set to `true`. Then, call `jobs.reports.list`, providing the job ID, to get the report's download URL, which may be filtered by creation or start times. Finally, use an HTTP GET request to download the report. Remember to store downloaded report details to avoid reprocessing.\n"],null,["# YouTube Reporting API - Get Bulk Data Reports\n\nYouTube automatically generates a set of system-managed ad revenue reports for content owners that have access to the corresponding reports in [Creator Studio](http://studio.youtube.com/). These reports are designed to provide programmatic access to data that is also available in manually downloadable reports accessible in the [Reports menu](https://support.google.com/youtube/answer/7648605) of the YouTube Creator Studio.\n\n**Note:** The API provides access to a different set of reports than Creator Studio, though the reports contain similar data. API reports might have different fields and also use different field names than Creator Studio reports.\n\nSince YouTube automatically generates system-managed reports, the process for retrieving these reports is different than for the YouTube Analytics bulk data reports available via the API.\n\nRetrieving reports\n------------------\n\nThe following steps explain how to retrieve system-managed reports via the API.\n\n### Step 1: Retrieve authorization credentials\n\nAll YouTube Reporting API requests must be authorized. The [Authorization guide](/youtube/reporting/guides/authorization) explains how to use the OAuth 2.0 protocol to retrieve authorization tokens.\n\nYouTube Reporting API requests use the following authorization scopes:\n\n| Scopes ||\n|----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| https://www.googleapis.com/auth/yt-analytics.readonly | View YouTube Analytics reports for your YouTube content. This scope provides access to user activity metrics, like view counts and rating counts. |\n| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | View YouTube Analytics monetary reports for your YouTube content. This scope provides access to user activity metrics and to estimated revenue and ad performance metrics. |\n\n### Step 2: Retrieve the job ID for the desired report\n\nCall the `jobs.list` method to retrieve a list of system-managed jobs. Set the [includeSystemManaged](/youtube/reporting/v1/reference/rest/v1/jobs/list#includeSystemManaged) parameter to `true`.\n\nThe [reportTypeId](/youtube/reporting/v1/reference/rest/v1/jobs#reportTypeId) property in each returned `Job` resource identifies the type of system-managed report associated with that job. Your application needs the [id](/youtube/reporting/v1/reference/rest/v1/jobs#id) property value from the same resource in the following step.\n\nThe [Reports](/youtube/reporting/v1/reports/system_managed/reports) document lists available reports, their report type IDs, and the fields they contain. You can also use the [reportTypes.list](/youtube/reporting/v1/reference/rest/v1/reportTypes/list) method to retrieve a list of supported report types.\n\n### Step 3: Retrieve the report's download URL\n\nCall the `jobs.reports.list` method to retrieve a list of reports created for the job. In the request, set the [jobId](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#jobId) parameter to the job ID of the report that you want to retrieve.\n\nYou can filter the list of reports using any or all of the following parameters:\n\n- Use the [createdAfter](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#createdAfter) parameter to indicate that the API should only return reports created after a specified time. This parameter can be used to ensure that the API only returns reports that you have not already processed.\n\n- Use the [startTimeBefore](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#startTimeBefore) parameter to indicate that the API response should only contain reports if the earliest data in the report is before the specified date. Whereas the `createdAfter` parameter pertains to the time the report was created, this date pertains to the data in the report.\n\n- Use the [startTimeAtOrAfter](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#startTimeAtOrAfter) parameter to indicate that the API response should only contain reports if the earliest data in the report is on or after the specified date. Like the `startTimeBefore` parameter, this parameter value corresponds to the data in the report and not the time the report was created.\n\nThe API response contains a list of `Report` resources for that job. Each resource refers to a report that contains data for a unique period.\n\n- The resource's [startTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#startTime) and [endTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#endTime) properties identify the time period that the report's data covers.\n- The resource's [downloadUrl](/youtube/reporting/v1/reference/rest/v1/jobs.reports#downloadUrl) property identifies the URL from which the report can be fetched.\n- The resource's [createTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) property specifies the date and time when the report was generated. Your application should store this value and use it to determine whether previously downloaded reports have changed.\n\n### Step 4: Download the report\n\nSend an HTTP GET request to the `downloadUrl` obtained in step 4 to retrieve the report.\n\nProcessing reports\n------------------\n\n### Best practices\n\nApplications that use the YouTube Reporting API should *always* follow these practices:\n\n- Use a report's header row to determine the ordering of the report's columns. For example, do not assume that [views](/youtube/reporting/v1/reports/metrics#views) will be the first metric returned in a report just because it is the first metric listed in a report description. Instead, use the report's header row to determine which column contains that data.\n\n- Keep a record of the reports you have downloaded to avoid repeatedly processing the same report. The following list suggests a couple of ways to do that.\n\n - When calling the [reports.list](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list) method, use the [createdAfter](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#createdAfter) parameter to only retrieve reports created after a certain date. (Omit the `createdAfter` parameter the first time you retrieve reports.)\n\n Each time you retrieve and successfully process reports, store the timestamp corresponding to the [date and time](/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) when the newest of those reports was created. Then, update the `createdAfter` parameter value on each successive call to the [reports.list](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list) method to ensure that you are only retrieving new reports, including new reports with backfilled data, each time you call the API.\n\n As a safeguard, before retrieving a report, also check to ensure that the report's [ID](/youtube/reporting/v1/reference/rest/v1/jobs.reports#id) is not already listed in your database.\n - Store the [ID](/youtube/reporting/v1/reference/rest/v1/jobs.reports#id) for each report that you have downloaded and processed. You can also store additional information like the [date and time](/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) when each report was generated or the report's [startTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#startTime) and [endTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#endTime), which together identify the period for which the report contains data. For reports that retrieve bulk data for YouTube Analytics, each job will likely have many reports since each report contains data for a 24-hour period. System-managed jobs that cover longer time periods will have fewer reports.\n\n Use the report ID to identify reports that you still need to download and import. However, if two new reports have the same [startTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#startTime) and [endTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#endTime) property values, only import the report with the newer [createTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) value.\n\n### Report characteristics\n\nAPI reports are versioned `.csv` (comma-separated values) files that have the following characteristics:\n\n- Each report contains data for a unique period lasting from 12:00 a.m. Pacific time on the report's start date through 11:59 p.m. Pacific time on the report's end date.\n\n- Report data is not sorted."]]
