Чтобы обсудить наши продукты и оставить отзыв о них, присоединяйтесь к официальному каналу Ad Manager Discord на сервере Google Advertising and Measurement Community .

Эта страница переведена с помощью Cloud Translation API.

Запуск отчетов

Вы можете создать интерактивный отчет, запустить существующий отчет и прочитать результаты отчета с помощью API Менеджера рекламы.

Если вы не знакомы с интерактивными отчетами в Ad Manager, ознакомьтесь с разделом Создание интерактивного отчета, где приведены общие сведения о том, как использовать интерактивные отчеты в пользовательском интерфейсе Ad Manager.

Для сложных отчетов вы можете использовать пользовательский интерфейс Ad Manager для проверки совместимости измерений и метрик. Все отчеты пользовательского интерфейса можно запустить с помощью API.

В этом руководстве рассматривается, как инициировать асинхронный запуск Report , опросить возвращенный статус Operation , получить имя ресурса Result из завершенной Operation и извлечь постраничный набор Rows результата.

Предпосылки

Прежде чем продолжить, убедитесь, что у вас есть доступ к сети Google Ad Manager. Чтобы получить доступ, см. раздел Начало работы с Google 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 является заполнителем для идентификатора отчета, а 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();
    }
  }
}SyncRunReportReportname.java

Питон

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)admanager_v1_generated_report_service_run_report_sync.py

.СЕТЬ

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;
        }
    }
}ReportServiceClient.RunReportResourceNamesSnippet.g.cs

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);
}run_report.php

Рубин

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
endrun_report.rb

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();report_service.run_report.js

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();
  }
}SyncRunReport.java

Питон

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)

.СЕТЬ

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);

Рубин

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();

Питон

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

.СЕТЬ

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();
}

Рубин

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
}

Если вы используете клиентскую библиотеку, ответ содержит итератор, который лениво запрашивает дополнительные страницы. Вы также можете использовать параметры 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()) {
      }
    }
  }
}SyncFetchReportResultRowsString.java

Питон

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)admanager_v1_generated_report_service_fetch_report_result_rows_sync.py

.СЕТЬ

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;
    }
}ReportServiceClient.FetchReportResultRowsSnippet.g.cs

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());
    }
}fetch_report_result_rows.php

Рубин

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
endfetch_report_result_rows.rb

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();report_service.fetch_report_result_rows.js

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, которого вы аутентифицируете, имеет доступ к интерактивному отчету. Вы можете читать только интерактивные отчеты из API Ad Manager.
Почему результаты отчета по моей тестовой сети пусты?: Тестовые сети не показывают рекламу, поэтому в отчетах о доставке нет данных.
Почему результаты отчета по моей производственной сети пусты?: Пользователь, под которым вы аутентифицируетесь, может не иметь доступа к данным, по которым вы пытаетесь создать отчет. Убедитесь, что разрешения его ролей и команды установлены правильно.
Почему количество кликов и показов за все время не соответствует моему отчету в пользовательском интерфейсе?: Показы за все время действия относятся ко всему сроку действия позиции, независимо от диапазона дат отчета. Если позиция все еще выполняется, значение может измениться между двумя запусками одного и того же отчета.

Запуск отчетов Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Предпосылки

Запустить отчет

Ява

Питон

.СЕТЬ

PHP

Рубин

Node.js

cURL

Запрос

Ответ

Опросить статус отчета

Ява

Питон

.СЕТЬ

PHP

Рубин

Node.js

cURL

Запрос

Ответ

Получить имя ресурса результата

Ява

Питон

.СЕТЬ

PHP

Рубин

Node.js

cURL

Запрос

Ответ

Прочитать строки результатов

Отчет Определение

Ответ fetchRows

Ява

Питон

.СЕТЬ

PHP

Рубин

Node.js

cURL

Устранение неполадок с помощью отчета

Запуск отчетов

Ответ `fetchRows`