אפשר ליצור דוח אינטראקטיבי, להריץ דוח קיים ולקרוא את תוצאות הדוח באמצעות Ad Manager API.
אם אתם לא יודעים איך משתמשים בדוחות אינטראקטיביים ב-Ad Manager, כדאי לעיין במאמר יצירת דוח אינטראקטיבי כדי לקבל סקירה כללית על השימוש בדוחות אינטראקטיביים בממשק המשתמש של Ad Manager.
בדוחות מורכבים, אפשר להשתמש בממשק המשתמש של Ad Manager כדי לבדוק את התאימות של המאפיינים והמדדים. אפשר להריץ את כל הדוחות בממשק המשתמש באמצעות ה-API.
במדריך הזה נסביר איך מפעילים הפעלה אסינכררונית של Report
, בודקים את הסטטוס Operation
שמוחזר, מקבלים את שם המשאב Result
מהפעולה שהושלמו Operation
ומאחזרים קבוצת תוצאות עם דפים Rows
.
דרישות מוקדמות
לפני שממשיכים, צריך לוודא שיש לכם גישה לרשת של Google Ad Manager. במאמר תחילת העבודה עם Google Ad Manager מוסבר איך מקבלים גישה.
הרצת דוח
כדי להריץ דוח, צריך את מזהה הדוח. אפשר לקבל מזהה דוח בממשק המשתמש של Ad Manager דרך כתובת ה-URL של הדוח. לדוגמה, בכתובת ה-URL https://admanager.google.com/234093456#reports/interactive/detail/report_id=4555265029
מזהה הדוח הוא 4555265029
.
אפשר גם לקרוא דוחות שיש למשתמש גישה אליהם באמצעות השיטה networks.reports.list
ולקבל את המזהה משם המשאב:
networks/234093456/reports/4555265029
אחרי שמקבלים את מזהה הדוח, אפשר להפעיל את הדוח באופן אסינכרוני באמצעות השיטה networks.reports.run
. השיטה הזו מחזירה את שם המשאב של Operation
ממושכת.
שימו לב שבקוד לדוגמה הבא, REPORT_ID
הוא placeholder למזהה הדוח ו-NETWORK_CODE
הוא placeholder לקוד הרשת. במאמר איך מוצאים את פרטי חשבון 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_ID");
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_ID", ) # 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_ID");
// 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;
}
}
}
PHP
use Google\Ads\AdManager\V1\Client\ReportServiceClient;
use Google\Ads\AdManager\V1\RunReportRequest;
use Google\Ads\AdManager\V1\RunReportResponse;
use Google\ApiCore\ApiException;
use Google\ApiCore\OperationResponse;
use Google\Rpc\Status;
function run_report_sample(string $formattedName): void
{
// Create a client.
$reportServiceClient = new ReportServiceClient();
// Prepare the request message.
$request = (new RunReportRequest())
->setName($formattedName);
// Call the API and handle any network failures.
try {
$response = $reportServiceClient->runReport($request);
$response->pollUntilComplete();
if ($response->operationSucceeded()) {
$result = $response->getResult();
printf('Operation successful with response data: %s' . PHP_EOL, $result->serializeToJsonString());
} else {
$error = $response->getError();
printf('Operation failed with error data: %s' . PHP_EOL, $error->serializeToJsonString());
}
} catch (ApiException $ex) {
printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
}
}
function callSample(): void
{
$formattedName = ReportServiceClient::reportName('NETWORK_CODE', 'REPORT_ID');
run_report_sample($formattedName);
}
Ruby
require "google/ads/ad_manager/v1"
def run_report
# Create a client object. The client can be reused for multiple calls.
client = Google::Ads::AdManager::V1::ReportService::Rest::Client.new
# Create a request. To set request fields, pass in keyword arguments.
request = Google::Ads::AdManager::V1::RunReportRequest.new(
:name => 'networks/NETWORK_CODE/reports/REPORT_ID'
)
# Call the run_report method.
result = client.run_report request
# The returned object is of type Gapic::Operation. You can use it to
# check the status of an operation, cancel it, or wait for results.
# Here is how to wait for a response.
result.wait_until_done! timeout: 60
if result.response?
p result.response
else
puts "No response received."
end
end
Node.js
const name = 'networks/NETWORK_CODE/reports/REPORT_ID';
// Imports the Admanager library
const {ReportServiceClient} = require('@google-ads/admanager').v1;
// Instantiates a client
const admanagerClient = new ReportServiceClient();
async function callRunReport() {
// Construct request
const request = {
name,
};
// Run request
const [operation] = await admanagerClient.runReport(request);
const [response] = await operation.promise();
console.log(response);
}
callRunReport();
cURL
בקשה
curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" \ "https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/reports/{$REPORT_ID}:run"
תשובה
{ "name": "networks/234093456/operations/reports/runs/6485392645", "metadata": { "@type": "type.googleapis.com/google.ads.admanager.v1.RunReportMetadata", "report": "networks/234093456/reports/4555265029" } }
סקרים לגבי סטטוס הדוח
אם אתם משתמשים בספריית לקוח, קוד הדוגמה בקטע הקודם בודק את סטטוס ההרצה של הדוח Operation
במרווחי הזמן המומלצים ומספק את התוצאה בסיום. למידע נוסף על מרווחי הזמן המומלצים לבדיקות, ראו networks.reports.run
.
אם אתם רוצים לשלוט יותר בסקרים, תוכלו לשלוח בקשה ספציפית לאחזור הסטטוס הנוכחי של דוח פעיל באמצעות השיטה 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; }
PHP
$options = [
'initialPollDelayMillis' => 500, // Initial delay of 500ms
'pollDelayMultiplier' => 1.5,
'maxPollDelayMillis' => 30000, // Max poll delay of 30 seconds
'totalPollTimeoutMillis' => 60 * 60 * 1000, // Total timeout of 1 hour in milliseconds
];
$response = $reportServiceClient->runReport($request);
$response->pollUntilComplete($options);
Ruby
options = {
initial_delay: 0.5, # Initial delay of 500ms (0.5 seconds)
multiplier: 1.5,
max_delay: 30.0, # Max poll delay of 30 seconds
timeout: 60 * 60 # Total timeout of 1 hour in seconds
}
result = client.run_report request
result.wait_until_done!(retry_policy: options)
if result.response?
p result.response
else
puts "No response received."
end
Node.js
const options = {
initialRetryDelayMillis: 500, // Initial delay of 500ms
retryDelayMultiplier: 1.5,
maxRetryDelayMillis: 30, // Max poll delay of 30 seconds
totalTimeoutMillis: 60 * 60 * 1000 // Total timeout of 1 hour
}
const [operation] = await admanagerClient.runReport(request);
operation.backoffSettings = options;
const [response] = await operation.promise();
console.log(response);
cURL
בקשה
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/operations/reports/runs/${OPERATION_ID}"
תשובה
{ "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, }
אחזור שם המשאב של התוצאה
בסיום ההרצה של הדוח Operation
, הוא מכיל את שם המשאב של 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;
PHP
$response = $reportServiceClient->runReport($request);
$response->pollUntilComplete();
if ($response->operationSucceeded()) {
$result = $response->getResult();
// Result name in the format networks/[NETWORK_CODE]/reports/[REPORT_ID]/results/[RESULT_ID]
$resultName = $result->getReportResult();
}
Ruby
result = client.run_report request
result.wait_until_done!
if result.response?
# Result name in the format networks/[NETWORK_CODE]/reports/[REPORT_ID]/results/[RESULT_ID]
p result.response.report_result
else
puts "No response received."
end
Node.js
// Run request
const [operation] = await admanagerClient.runReport(request);
const [response] = await operation.promise();
// Result name in the format networks/[NETWORK_CODE]/reports/[REPORT_ID]/results/[RESULT_ID]
console.log(response.reportResult);
cURL
בקשה
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/operations/reports/runs/${OPERATION_ID}"
תשובה
{ "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" } }
קריאת שורות התוצאה
למשאב Result
יש שיטה אחת, networks.reports.results.fetchRows
, לקריאת רשימה של שורות שמחולקות לדפים. בכל שורה מופיעה רשימה של ערכי מאפיינים ורשימה של ערכי מדדים מקובצים. כל קבוצה מכילה את ערך המדד ואת ערכי ההשוואה או הדגלים. למידע נוסף על דגלים, ראו שימוש בדגלים בדוח האינטראקטיבי.
בדוחות ללא השוואות או חלוקות של טווחי תאריכים, יש רק MetricValueGroup
אחד עם ערכי מדדים (לדוגמה, חשיפות או קליקים) לכל טווח התאריכים של הדוח.
סדר הערכים של המאפיינים והמדדים זהה לסדר שמופיע ב-ReportDefinition
של Report
.
בהמשך מופיעה דוגמה ל-JSON של ReportDefinition
ותגובה תואמת של fetchRows
:
הגדרת דוח
{
"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": {}
}
fetchRows
תגובה
{
"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
}
אם אתם משתמשים בספריית לקוח, התגובה כוללת מעבד (iterator) שמבקש דפים נוספים באופן עצלני. אפשר גם להשתמש בפרמטר pageToken
ובפרמטר pageSize
. פרטים על הפרמטרים האלה מופיעים בקטע פרמטרים של שאילתות.
אם יש דף נוסף, התשובה תכיל את השדה nextPageToken
עם האסימון שצריך להשתמש בו בבקשה הבאה.
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(
name = "networks/NETWORK_CODE/reports/REPORT_ID/results/RESULT_ID"
)
# 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;
}
}
PHP
use Google\Ads\AdManager\V1\Client\ReportServiceClient;
use Google\Ads\AdManager\V1\FetchReportResultRowsRequest;
use Google\Ads\AdManager\V1\FetchReportResultRowsResponse;
use Google\ApiCore\ApiException;
function fetch_report_result_rows_sample(): void
{
// Create a client.
$reportServiceClient = new ReportServiceClient();
// Prepare the request message.
$request = (new FetchReportResultRowsRequest())
->setName('networks/NETWORK_CODE/reports/REPORT_ID/results/RESULT_ID');
// Call the API and handle any network failures.
try {
$response = $reportServiceClient->fetchReportResultRows($request);
printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
} catch (ApiException $ex) {
printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
}
}
Ruby
require "google/ads/ad_manager/v1"
def fetch_report_result_rows
# Create a client object. The client can be reused for multiple calls.
client = Google::Ads::AdManager::V1::ReportService::Rest::Client.new
# Create a request. To set request fields, pass in keyword arguments.
request = Google::Ads::AdManager::V1::FetchReportResultRowsRequest.new(
:name => 'networks/NETWORK_CODE/reports/REPORT_ID/results/RESULT_ID'
)
# Call the fetch_report_result_rows method.
result = client.fetch_report_result_rows request
# The returned object is of type Gapic::PagedEnumerable. You can iterate
# over elements, and API calls will be issued to fetch pages as needed.
result.each do |item|
# Each element is of type ::Google::Ads::AdManager::V1::Report::DataTable::Row.
p item
end
end
Node.js
const name = 'networks/NETWORK_CODE/reports/REPORT_ID/results/RESULT_ID';
// Imports the Admanager library
const {ReportServiceClient} = require('@google-ads/admanager').v1;
// Instantiates a client
const admanagerClient = new ReportServiceClient();
async function callFetchReportResultRows() {
// Construct request
const request = {
name,
};
// Run request
const iterable = admanagerClient.fetchReportResultRowsAsync(request);
for await (const response of iterable) {
console.log(response);
}
}
callFetchReportResultRows();
cURL
הבקשה הראשונית
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/reports/${REPORT_ID}/results/${RESULT_ID}:fetchRows"
בקשה לדף הבא
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"https://admanager.googleapis.com/v1/networks/${NETWORK_CODE}/reports/${REPORT_ID}/results/${RESULT_ID}:fetchRows?pageToken=${PAGE_TOKEN}"
פתרון בעיות בדוח
- למה הדוח שלי לא מוחזר ב-API?
- מוודאים שלמשתמש ב-Ad Manager שאיתו מבצעים את האימות יש גישה לדוח האינטראקטיבי. אפשר לקרוא דוחות אינטראקטיביים רק מ-Ad Manager API.
- למה תוצאות הדוחות ברשת הבדיקה שלי ריקות?
- ברשתות הבדיקה לא מוצגות מודעות, ולכן בדוחות ההצגה לא מוצגים נתונים.
- למה תוצאות הדוח ברשת הייצור שלי ריקות?
- יכול להיות שלמשתמש שאתם מבצעים אימות בשם שלו אין גישה לנתונים שאתם מנסים לדווח עליהם. מוודאים שהרשאות התפקיד והצוותים מוגדרים בצורה נכונה.
- למה מספר הקליקים או החשיפות במצטבר לא תואמים לדוח שלי בממשק המשתמש?
- החשיפות בכל משך החיים מתייחסות לכל משך החיים של הפריט, ללא קשר לטווח התאריכים של הדוח. אם פריט שורה עדיין מניב ביצועים, הערך עשוי להשתנות בין שתי הפעלות של אותו דוח.