Вы можете создать интерактивный отчет, запустить существующий отчет и прочитать результаты отчета с помощью API Менеджера рекламы.
Если вы не знакомы с интерактивными отчетами в Менеджере рекламы, ознакомьтесь с разделом Создание интерактивного отчета , чтобы узнать, как использовать интерактивные отчеты в пользовательском интерфейсе Менеджера рекламы.
Для сложных отчетов вы можете использовать интерфейс Менеджера рекламы, чтобы проверить совместимость параметров и показателей. Все отчеты пользовательского интерфейса можно запускать с помощью API.
В этом руководстве описывается, как инициировать асинхронный запуск Report , опросить возвращенный статус Operation , получить имя ресурса Result из завершенной Operation и получить разбитый на страницы набор Rows результатов.
Предварительное условие
Прежде чем продолжить, убедитесь, что у вас есть доступ к сети Google Ad Manager. Чтобы получить доступ, ознакомьтесь со статьей Начало работы с Google Ad Manager .
Запустить отчет
Чтобы запустить отчет, вам понадобится идентификатор отчета. Вы можете получить идентификатор отчета в интерфейсе Менеджера рекламы по URL-адресу отчета. Например, в URL https://www.google.com/admanager/234093456#reports/interactive/detail/report_id=4555265029 идентификатор отчета — 4555265029 .
Вы также можете прочитать отчеты, к которым у вашего пользователя есть доступ, используя метод networks.reports.list и получить идентификатор из имени ресурса:
networks/234093456/reports/4555265029
Получив идентификатор отчета, вы можете инициировать асинхронный запуск отчета с помощью метода networks.reports.run . Этот метод возвращает имя ресурса длительно выполняемой Operation . Обратите внимание, что в следующем примере кода [REPORT] — это заполнитель для идентификатора отчета, а [NETWORK] — это заполнитель для вашего сетевого кода. Чтобы узнать код своей сети, см. раздел «Поиск информации об аккаунте Менеджера рекламы» .
Ява
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();
}
}
}
Питон
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)
.СЕТЬ
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 -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();
}
}
Питон
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; }
КУЛЬ
Запрос
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;
КУЛЬ
Запрос
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": {}
}
{
"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()) {
}
}
}
}
Питон
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)
.СЕТЬ
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 -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?
- Убедитесь, что пользователь Менеджера рекламы, под которым вы проходите аутентификацию, имеет доступ к интерактивному отчету. Вы можете читать интерактивные отчеты только из API Менеджера рекламы.
- Почему результаты отчета в моей тестовой сети пусты?
- Тестовые сети не показывают рекламу, поэтому в отчетах о доставке нет данных.
- Почему результаты отчета в моей производственной сети пусты?
- Пользователь, под которым вы проходите аутентификацию, может не иметь доступа к данным, о которых вы пытаетесь сообщить. Убедитесь, что разрешения ролей и команды установлены правильно.
- Почему количество кликов или показов за весь период не соответствует моему отчету в пользовательском интерфейсе?
- Показы за весь срок действия производятся в течение всего срока действия позиции, независимо от диапазона дат отчета. Если позиция по-прежнему выполняется, значение может измениться между двумя запусками одного и того же отчета.