보고서 실행

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이 있습니다.

측정기준 및 측정항목 값의 순서는 ReportReportDefinition 순서와 동일합니다.

다음은 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
}

클라이언트 라이브러리를 사용하는 경우 응답에는 추가 페이지를 지연 로드하는 반복자가 있습니다. pageTokenpageSize 매개변수를 사용할 수도 있습니다. 이러한 매개변수에 관한 자세한 내용은 쿼리 매개변수를 참고하세요. 다른 페이지가 있는 경우 응답에는 다음 요청에 사용할 토큰이 포함된 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의 보고서와 일치하지 않는 이유는 무엇인가요?
전체 기간 노출수는 보고서 기간과 관계없이 광고 항목의 전체 기간에 대한 노출수입니다. 광고 항목이 아직 게재 중인 경우 동일한 보고서를 두 번 실행할 때 값이 달라질 수 있습니다.