Bạn có thể tạo Báo cáo tương tác, chạy báo cáo hiện có và đọc kết quả báo cáo bằng API Ad Manager.
Nếu bạn chưa quen với báo cáo Tương tác trong Ad Manager, hãy xem bài viết Tạo báo cáo Tương tác để biết thông tin tổng quan về cách sử dụng báo cáo Tương tác trong giao diện người dùng Ad Manager.
Đối với các báo cáo phức tạp, bạn có thể sử dụng giao diện người dùng Ad Manager để kiểm tra khả năng tương thích của phương diện và chỉ số. Bạn có thể chạy tất cả báo cáo trên giao diện người dùng bằng API.
Hướng dẫn này trình bày cách bắt đầu chạy không đồng bộ của Report, thăm dò ý kiến về trạng thái Operation được trả về, lấy tên tài nguyên Result từ Operation đã hoàn tất và tìm nạp một tập hợp kết quả phân trang Rows.
Điều kiện tiên quyết
Trước khi tiếp tục, hãy đảm bảo bạn có quyền truy cập vào một mạng Google Ad Manager. Để có quyền truy cập, hãy xem bài viết Bắt đầu sử dụng Google Ad Manager.
Chạy báo cáo
Để chạy báo cáo, bạn cần có mã báo cáo. Bạn có thể lấy mã báo cáo trong giao diện người dùng Ad Manager thông qua URL báo cáo. Ví dụ: trong URL https://www.google.com/admanager/234093456#reports/interactive/detail/report_id=4555265029, mã báo cáo là 4555265029.
Bạn cũng có thể đọc các báo cáo mà người dùng có quyền truy cập bằng phương thức networks.reports.list và lấy mã nhận dạng từ tên tài nguyên:
networks/234093456/reports/4555265029
Sau khi có mã báo cáo, bạn có thể bắt đầu chạy báo cáo không đồng bộ bằng phương thức networks.reports.run. Phương thức này trả về tên tài nguyên của một Operation chạy trong thời gian dài.
Xin lưu ý rằng trong mã ví dụ sau, [REPORT] là phần giữ chỗ cho mã báo cáo và [NETWORK] là phần giữ chỗ cho mã mạng của bạn. Để tìm mã mạng, hãy xem bài viết Tìm thông tin tài khoản Ad Manager.
Java
import com.google.ads.admanager.v1.ReportName;
import com.google.ads.admanager.v1.ReportServiceClient;
import com.google.ads.admanager.v1.RunReportResponse;
public class SyncRunReportReportname {
public static void main(String[] args) throws Exception {
syncRunReportReportname();
}
public static void syncRunReportReportname() throws Exception {
try (ReportServiceClient reportServiceClient = ReportServiceClient.create()) {
ReportName name = ReportName.of("[NETWORK_CODE]", "[REPORT]");
RunReportResponse response = reportServiceClient.runReportAsync(name).get();
}
}
}
Python
from google.ads import admanager_v1 def sample_run_report(): # Create a client client = admanager_v1.ReportServiceClient() # Initialize request argument(s) request = admanager_v1.RunReportRequest( name="networks/[NETWORK_CODE]/reports/[REPORT]", ) # Make the request operation = client.run_report(request=request) print("Waiting for operation to complete...") response = operation.result() # Handle the response print(response)
.NET
using Google.Ads.AdManager.V1;
using Google.LongRunning;
public sealed partial class GeneratedReportServiceClientSnippets
{
public void RunReportResourceNames()
{
// Create client
ReportServiceClient reportServiceClient = ReportServiceClient.Create();
// Initialize request argument(s)
ReportName name = ReportName.FromNetworkCodeReport("[NETWORK_CODE]", "[REPORT]");
// Make the request
Operation<RunReportResponse, RunReportMetadata> response = reportServiceClient.RunReport(name);
// Poll until the returned long-running operation is complete
Operation<RunReportResponse, RunReportMetadata> completedResponse = response.PollUntilCompleted();
// Retrieve the operation result
RunReportResponse result = completedResponse.Result;
// Or get the name of the operation
string operationName = response.Name;
// This name can be stored, then the long-running operation retrieved later by name
Operation<RunReportResponse, RunReportMetadata> retrievedResponse = reportServiceClient.PollOnceRunReport(operationName);
// Check if the retrieved long-running operation has completed
if (retrievedResponse.IsCompleted)
{
// If it has completed, then access the result
RunReportResponse retrievedResult = retrievedResponse.Result;
}
}
}
cURL
Yêu cầu
curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" \ "https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/reports/{$REPORT_ID}:run"
Phản hồi
{ "name": "networks/234093456/operations/reports/runs/6485392645", "metadata": { "@type": "type.googleapis.com/google.ads.admanager.v1.RunReportMetadata", "report": "networks/234093456/reports/4555265029" } }
Thăm dò trạng thái báo cáo
Nếu bạn đang sử dụng thư viện ứng dụng, mã ví dụ của phần trước sẽ thăm dò ý kiến về trạng thái của báo cáo chạy Operation theo các khoảng thời gian được đề xuất và cung cấp kết quả khi báo cáo hoàn tất. Để biết thêm thông tin về khoảng thời gian thăm dò ý kiến được đề xuất, hãy xem networks.reports.run.
Nếu bạn muốn kiểm soát nhiều hơn việc thăm dò ý kiến, hãy tạo một yêu cầu riêng để truy xuất trạng thái hiện tại của báo cáo đang chạy bằng phương thức networks.operations.reports.runs.get:
Java
import com.google.ads.admanager.v1.ReportServiceSettings;
import com.google.api.gax.longrunning.OperationalTimedPollAlgorithm;
import com.google.api.gax.retrying.RetrySettings;
import com.google.api.gax.retrying.TimedRetryAlgorithm;
import java.time.Duration;
public class SyncRunReport {
public static void main(String[] args) throws Exception {
syncRunReport();
}
public static void syncRunReport() throws Exception {
ReportServiceSettings.Builder reportServiceSettingsBuilder = ReportServiceSettings.newBuilder();
TimedRetryAlgorithm timedRetryAlgorithm =
OperationalTimedPollAlgorithm.create(
RetrySettings.newBuilder()
.setInitialRetryDelayDuration(Duration.ofMillis(500))
.setRetryDelayMultiplier(1.5)
.setMaxRetryDelayDuration(Duration.ofMillis(5000))
.setTotalTimeoutDuration(Duration.ofHours(24))
.build());
reportServiceSettingsBuilder
.createClusterOperationSettings()
.setPollingAlgorithm(timedRetryAlgorithm)
.build();
}
}
Python
from google.ads import admanager_v1 from google.longrunning.operations_pb2 import GetOperationRequest def sample_poll_report(): # Run the report client = admanager_v1.ReportServiceClient() response = client.run_report(name="networks/[NETWORK_CODE]/reports/[REPORT_ID]") # Check if the long-running operation has completed operation = client.get_operation( GetOperationRequest(name=response.operation.name)) if(operation.done): # If it has completed, then access the result run_report_response = admanager_v1.RunReportResponse.deserialize(payload=operation.response.value)
.NET
Operation<RunReportResponse, RunReportMetadata> retrievedResponse = reportServiceClient.PollOnceRunReport(operationName); // Check if the retrieved long-running operation has completed if (retrievedResponse.IsCompleted) { // If it has completed, then access the result RunReportResponse retrievedResult = retrievedResponse.Result; }
cURL
Yêu cầu
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/operations/reports/runs/${OPERATION_ID}"
Phản hồi
{ "name": "networks/234093456/operations/reports/runs/6485392645", "metadata": { "@type": "type.googleapis.com/google.ads.admanager.v1.RunReportMetadata", "percentComplete": 50, "report": "networks/234093456/reports/4555265029" }, "done": false, }
Lấy tên tài nguyên kết quả
Sau khi chạy báo cáo Operation xong, báo cáo sẽ chứa tên tài nguyên của Result.
Java
RunReportResponse response = reportServiceClient.runReportAsync(name).get();
// Result name in the format networks/[NETWORK_CODE]/reports/[REPORT_ID]/results/[RESULT_ID]
String resultName = response.getReportResult();
Python
operation = client.run_report(request=request)
response = operation.result()
# Result name in the format networks/[NETWORK_CODE]/reports/[REPORT_ID]/results/[RESULT_ID]
result_name = response.report_result
.NET
Operation<RunReportResponse, RunReportMetadata> response = reportServiceClient.RunReport(request);
// Poll until the returned long-running operation is complete
Operation<RunReportResponse, RunReportMetadata> completedResponse = response.PollUntilCompleted();
RunReportResponse result = completedResponse.Result;
// Result name in the format networks/[NETWORK_CODE]/reports/[REPORT_ID]/results/[RESULT_ID]
string resultName = result.ReportResult;
cURL
Yêu cầu
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/operations/reports/runs/${OPERATION_ID}"
Phản hồi
{ "name": "networks/234093456/operations/reports/runs/6485392645", "metadata": { "@type": "type.googleapis.com/google.ads.admanager.v1.RunReportMetadata", "percentComplete": 100, "report": "networks/234093456/reports/4555265029" }, "done": true, "response": { "@type": "type.googleapis.com/google.ads.admanager.v1.RunReportResponse", "reportResult": "networks/234093456/reports/4555265029/results/7031632628" } }
Đọc hàng kết quả
Tài nguyên Result có một phương thức duy nhất là networks.reports.results.fetchRows để đọc danh sách các hàng được phân trang. Mỗi hàng có một danh sách giá trị phương diện và một danh sách giá trị chỉ số được nhóm. Mỗi nhóm chứa giá trị chỉ số và mọi giá trị hoặc cờ so sánh. Để biết thêm thông tin về cờ, hãy xem bài viết Sử dụng cờ trong báo cáo tương tác.
Đối với các báo cáo không có dữ liệu so sánh hoặc phân chia theo phạm vi ngày, sẽ có một MetricValueGroup duy nhất với các giá trị chỉ số (ví dụ: lượt hiển thị hoặc lượt nhấp) cho toàn bộ phạm vi ngày của báo cáo.
Thứ tự của các giá trị phương diện và chỉ số giống với thứ tự trong ReportDefinition của Report.
Sau đây là ví dụ về JSON của ReportDefinition và phản hồi fetchRows tương ứng:
{
"name": "networks/234093456/reports/4555265029",
"visibility": "SAVED",
"reportId": "4555265029",
"reportDefinition": {
"dimensions": [
"LINE_ITEM_NAME",
"LINE_ITEM_ID"
],
"metrics": [
"AD_SERVER_IMPRESSIONS"
],
"currencyCode": "USD",
"dateRange": {
"relative": "YESTERDAY"
},
"reportType": "HISTORICAL"
},
"displayName": "Example Report",
"updateTime": "2024-09-01T13:00:00Z",
"createTime": "2024-08-01T02:00:00Z",
"locale": "en-US",
"scheduleOptions": {}
}
{
"rows": [
{
"dimensionValues": [
{
"stringValue": "Line Item #1"
},
{
"intValue": "6378470710"
}
],
"metricValueGroups": [
{
"primaryValues": [
{
"intValue": "100"
}
]
}
]
},
{
"dimensionValues": [
{
"stringValue": "Line Item #2"
},
{
"intValue": "5457147368"
}
],
"metricValueGroups": [
{
"primaryValues": [
{
"intValue": "95"
}
]
}
]
}
],
"runTime": "2024-10-02T10:00:00Z",
"dateRanges": [
{
"startDate": {
"year": 2024,
"month": 10,
"day": 1
},
"endDate": {
"year": 2024,
"month": 10,
"day": 1
}
}
],
"totalRowCount": 2
}
Nếu bạn đang sử dụng thư viện ứng dụng, phản hồi sẽ có một trình lặp yêu cầu các trang bổ sung một cách lười biếng. Bạn cũng có thể sử dụng các tham số pageToken và pageSize. Để biết thông tin chi tiết về các tham số này, hãy xem phần Tham số truy vấn.
Nếu có một trang khác, phản hồi sẽ chứa trường nextPageToken có mã thông báo để sử dụng trong yêu cầu tiếp theo.
Java
import com.google.ads.admanager.v1.Report;
import com.google.ads.admanager.v1.ReportServiceClient;
public class SyncFetchReportResultRowsString {
public static void main(String[] args) throws Exception {
syncFetchReportResultRowsString();
}
public static void syncFetchReportResultRowsString() throws Exception {
try (ReportServiceClient reportServiceClient = ReportServiceClient.create()) {
String name = "networks/[NETWORK_CODE]/reports/[REPORT_ID]/results/[RESULT_ID]";
for (Report.DataTable.Row element :
reportServiceClient.fetchReportResultRows(name).iterateAll()) {
}
}
}
}
Python
from google.ads import admanager_v1
def sample_fetch_report_result_rows():
# Create a client
client = admanager_v1.ReportServiceClient()
# Initialize request argument(s)
request = admanager_v1.FetchReportResultRowsRequest(
)
# Make the request
page_result = client.fetch_report_result_rows(request=request)
# Handle the response
for response in page_result:
print(response)
.NET
using Google.Ads.AdManager.V1;
using Google.Api.Gax;
using System;
public sealed partial class GeneratedReportServiceClientSnippets
{
public void FetchReportResultRows()
{
// Create client
ReportServiceClient reportServiceClient = ReportServiceClient.Create();
// Initialize request argument(s)
string name = "";
// Make the request
PagedEnumerable<FetchReportResultRowsResponse, Report.Types.DataTable.Types.Row> response = reportServiceClient.FetchReportResultRows(name);
// Iterate over all response items, lazily performing RPCs as required
foreach (Report.Types.DataTable.Types.Row item in response)
{
// Do something with each item
Console.WriteLine(item);
}
// Or iterate over pages (of server-defined size), performing one RPC per page
foreach (FetchReportResultRowsResponse page in response.AsRawResponses())
{
// Do something with each page of items
Console.WriteLine("A page of results:");
foreach (Report.Types.DataTable.Types.Row item in page)
{
// Do something with each item
Console.WriteLine(item);
}
}
// Or retrieve a single page of known size (unless it's the final page), performing as many RPCs as required
int pageSize = 10;
Page<Report.Types.DataTable.Types.Row> singlePage = response.ReadPage(pageSize);
// Do something with the page of items
Console.WriteLine($"A page of {pageSize} results (unless it's the final page):");
foreach (Report.Types.DataTable.Types.Row item in singlePage)
{
// Do something with each item
Console.WriteLine(item);
}
// Store the pageToken, for when the next page is required.
string nextPageToken = singlePage.NextPageToken;
}
}
cURL
Yêu cầu ban đầu
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/reports/${REPORT_ID}/results/${RESULT_ID}:fetchRows"
Yêu cầu trang tiếp theo
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/reports/${REPORT_ID}/results/${RESULT_ID}:fetchRows?pageToken=${PAGE_TOKEN}"
Khắc phục sự cố với báo cáo
- Tại sao báo cáo của tôi không được trả về trong API?
- Đảm bảo rằng người dùng Ad Manager mà bạn đang xác thực có quyền truy cập vào Báo cáo tương tác. Bạn chỉ có thể đọc Báo cáo tương tác qua API Ad Manager.
- Tại sao kết quả báo cáo trên mạng thử nghiệm của tôi lại trống?
- Mạng thử nghiệm không phân phát quảng cáo, vì vậy, báo cáo phân phối sẽ không có dữ liệu.
- Tại sao kết quả báo cáo trên mạng sản xuất của tôi lại trống?
- Người dùng mà bạn đang xác thực có thể không có quyền truy cập vào dữ liệu mà bạn đang cố gắng báo cáo. Xác minh rằng quyền của vai trò và nhóm của họ được đặt chính xác.
- Tại sao số lượt nhấp hoặc số lượt hiển thị trong vòng đời không khớp với báo cáo của tôi trong giao diện người dùng?
- Số lượt hiển thị trên toàn bộ thời gian là số lượt hiển thị trong toàn bộ thời gian hoạt động của mục hàng, bất kể phạm vi ngày của báo cáo. Nếu một mục hàng vẫn đang phân phối, thì giá trị này có thể thay đổi giữa hai lần chạy của cùng một báo cáo.