Ad Manager API를 사용하여 양방향 보고서를 만들고, 기존 보고서를 실행하고, 보고서 결과를 읽을 수 있습니다.
Ad Manager의 양방향 보고에 익숙하지 않다면 양방향 보고서 만들기에서 Ad Manager UI에서 양방향 보고서를 사용하는 방법을 간략히 알아보세요.
복잡한 보고서의 경우 Ad Manager UI를 사용하여 측정기준 및 측정항목 호환성을 확인할 수 있습니다. 모든 UI 보고서는 API를 사용하여 실행할 수 있습니다.
이 가이드에서는 Report
의 비동기 실행을 시작하고, 반환된 Operation
상태를 폴링하고, 완료된 Operation
에서 Result
리소스 이름을 가져오고, 페이지가 생성된 결과 집합 Rows
을 가져오는 방법을 설명합니다.
기본 요건
계속하기 전에 Google Ad Manager 네트워크에 액세스할 수 있는 권한이 있는지 확인하세요. 액세스 권한을 얻으려면 Google Ad Manager 시작하기를 참고하세요.
보고서 실행
보고서를 실행하려면 보고서 ID가 필요합니다. 보고서 URL을 통해 Ad
Manager UI에서 보고서 ID를 가져올 수 있습니다. 예를 들어 URL https://admanager.google.com/234093456#reports/interactive/detail/report_id=4555265029
의 보고서 ID는 4555265029
입니다.
networks.reports.list
메서드를 사용하여 사용자가 액세스할 수 있는 보고서를 읽고 리소스 이름에서 ID를 가져올 수도 있습니다.
networks/234093456/reports/4555265029
보고서 ID를 가져온 후 networks.reports.run
메서드를 사용하여 보고서의 비동기 실행을 시작할 수 있습니다. 이 메서드는 장기 실행 Operation
의 리소스 이름을 반환합니다.
다음 코드 예에서 REPORT_ID
는 보고서 ID의 자리표시자이고 NETWORK_CODE
는 네트워크 코드의 자리표시자입니다. 네트워크 코드를 찾으려면 Ad Manager 계정 정보 찾기를 참고하세요.
자바
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
메서드를 사용하여 실행 중인 보고서의 현재 상태를 검색하는 개별 요청을 실행합니다. 일부 클라이언트 라이브러리는 맞춤 폴링 전략 설정도 지원합니다.
자바
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
의 리소스 이름이 포함됩니다.
자바
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
이 있습니다.
측정기준 및 측정항목 값의 순서는 Report
의 ReportDefinition
순서와 동일합니다.
다음은 ReportDefinition
및 상응하는 fetchRows
응답의 JSON 예입니다.
보고서 정의
{
"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
}
클라이언트 라이브러리를 사용하는 경우 응답에는 추가 페이지를 지연 로드하는 반복자가 있습니다. pageToken
및 pageSize
매개변수를 사용할 수도 있습니다. 이러한 매개변수에 관한 자세한 내용은 쿼리 매개변수를 참고하세요.
다른 페이지가 있는 경우 응답에는 다음 요청에 사용할 토큰이 포함된 nextPageToken
필드가 있습니다.
자바
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에서만 양방향 보고서를 읽을 수 있습니다.
- 테스트 네트워크의 보고서 결과가 비어 있는 이유는 무엇인가요?
- 테스트 네트워크는 광고를 게재하지 않으므로 전송 보고서에 데이터가 없습니다.
- 프로덕션 네트워크의 보고서 결과가 비어 있는 이유는 무엇인가요?
- 인증하는 사용자에게 보고하려는 데이터에 대한 액세스 권한이 없을 수 있습니다. 역할 권한 및 팀이 올바르게 설정되어 있는지 확인합니다.
- 전체 기간 클릭수 또는 노출수가 UI의 보고서와 일치하지 않는 이유는 무엇인가요?
- 전체 기간 노출수는 보고서 기간과 관계없이 광고 항목의 전체 기간에 대한 노출수입니다. 광고 항목이 아직 게재 중인 경우 동일한 보고서를 두 번 실행할 때 값이 달라질 수 있습니다.