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

Проведите опрос и просмотрите готовые отчеты.

Операция запуска отчета выполняется асинхронно как длительная операция, представленная объектом Operation . Чтобы определить, когда операция запуска отчета завершена, вы можете опрашивать объект Operation с помощью метода agencies.reports.operations.get .

Результаты выполненной операции создания отчета можно просмотреть с помощью метода agencies.reports.results.fetchRows . Выходные данные операции создания отчета представляют собой результаты отчета, основанные на объекте Report .

В этом руководстве описано, как использовать API Agencies & Brands для получения информации о ходе выполнения отчета, проверки его статуса и получения результатов завершенного выполнения отчета.

Прежде чем начать

Прежде чем продолжить, необходимо выполнить следующие действия:

Настройте аутентификацию .
Запустите формирование отчета , чтобы получить имя ресурса, используемого в длительной операции.

Статус опроса запущенного отчета

Для проверки статуса выполнения операции запуска отчета используйте метод agencies.reports.operations.get .

В следующем примере выполняется GET запрос для опроса операции:

ОТДЫХ

Запрос

curl \
  'https://agenciesandbrands.googleapis.com/v1/agencies/ACCOUNT_ID/reports/123456789/operations/10486370264' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --compressed

Замените следующее:

ACCOUNT_ID : ваш идентификатор учетной записи.
ACCESS_TOKEN : ваш токен доступа.

Ответ

В случае успеха ответом будет объект Operation , в котором поле done будет установлено в значение true , а полезная нагрузка response будет заполнена именем ресурса reportResult :

{
  "name": "agencies/ACCOUNT_ID/reports/123456789/operations/10486370264",
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.ads.agenciesandbrands.v1.RunReportMetadata",
    "percentComplete": 100
  },
  "response": {
    "@type": "type.googleapis.com/google.ads.agenciesandbrands.v1.RunReportResponse",
    "reportResult": "agencies/ACCOUNT_ID/reports/123456789/results/10486370264"
  }
}

Java

/*
 * Copyright (c) 2026 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */

package com.google.api.services.samples.agenciesandbrands.v1.agencies.reports.operations;

import com.google.api.services.agenciesandbrands.v1.AgenciesAndBrands;
import com.google.api.services.agenciesandbrands.v1.model.Operation;
import com.google.api.services.samples.agenciesandbrands.v1.Utils;
import java.io.IOException;
import java.security.GeneralSecurityException;
import net.sourceforge.argparse4j.ArgumentParsers;
import net.sourceforge.argparse4j.inf.ArgumentParser;
import net.sourceforge.argparse4j.inf.ArgumentParserException;
import net.sourceforge.argparse4j.inf.Namespace;

public class GetReportOperation {

  /**
   * Executes the get operation for a report operation.
   *
   * @param agenciesAndBrandsClient the initialized Agencies & Brands API client.
   * @param accountId the account ID of the agency.
   * @param reportId the resource ID of the report.
   * @param operationId the resource ID of the report operation.
   * @throws IOException if the API returns an error.
   */
  public static void execute(
      AgenciesAndBrands agenciesAndBrandsClient,
      Long accountId,
      String reportId,
      String operationId)
      throws IOException {
    String name =
        String.format(
            "agencies/%s/reports/%s/operations/%s", accountId, reportId, operationId);

    System.out.printf("Getting report operation with name \"%s\".%n", name);

    // Get the status of the report operation.
    Operation operation =
        agenciesAndBrandsClient
            .agencies()
            .reports()
            .operations()
            .get(name)
            .execute();

    System.out.println("Successfully retrieved report operation:");
    Utils.jsonPrettyPrint(operation);
  }

  /**
   * Creates and configures the ArgumentParser for this sample.
   *
   * @return the configured ArgumentParser.
   */
  private static ArgumentParser createArgumentParser() {
    ArgumentParser parser =
        ArgumentParsers.newFor("GetReportOperation")
            .build()
            .defaultHelp(true)
            .description("Gets the status of a long-running report operation. If the " +
                "operation is done, you can view the report contents with the " +
                "`agencies.reports.results.fetchRows` method.");

    // Required arguments.
    parser
        .addArgument("-a", "--account_id")
        .help("The account ID of the agency.")
        .required(true)
        .type(Long.class);
    parser
        .addArgument("-r", "--report_id")
        .help("The resource ID of the report.")
        .required(true);
    parser
        .addArgument("-o", "--operation_id")
        .help("The resource ID of the report operation to retrieve.")
        .required(true);

    return parser;
  }

  public static void main(String[] args) {
    ArgumentParser parser = createArgumentParser();

    Namespace parsedArgs = null;
    try {
      parsedArgs = parser.parseArgs(args);
    } catch (ArgumentParserException ex) {
      parser.handleError(ex);
      System.exit(1);
    }

    AgenciesAndBrands client = null;
    try {
      client = Utils.getAgenciesAndBrandsClient();
    } catch (IOException ex) {
      System.out.printf("Unable to create Agencies & Brands API service:%n%s", ex);
      System.out.println("Did you specify a valid path to a service account key file?");
      System.exit(1);
    } catch (GeneralSecurityException ex) {
      System.out.printf("Unable to establish secure HttpTransport:%n%s", ex);
      System.exit(1);
    }

    try {
      execute(
          client,
          parsedArgs.getLong("account_id"),
          parsedArgs.getString("report_id"),
          parsedArgs.getString("operation_id"));
    } catch (IOException ex) {
      System.out.printf("Agencies & Brands API returned error response:%n%s", ex);
      System.exit(1);
    }
  }
}

Ниже описано, как использовать поле done для проверки статуса операции:

Если поле done в ответе имеет значение false , операция выполнения отчета все еще выполняется.
Если поле done в ответе имеет значение true , операция выполнения отчета завершена. Объект Operation в теле ответа также содержит одно из следующих полей:
- response : Указывает на успешное выполнение операции создания отчета. Это поле представляет собой объект, заполненный полем @type , установленным на тип type.googleapis.com/google.ads.agenciesandbrands.v1.RunReportResponse . Тип RunReportResponse заполняется полем reportResult , содержащим имя соответствующего result отчета.
- error : указывает на сбой выполнения отчета. Поле error заполняется объектом Status , описывающим причину сбоя выполнения отчета.

Извлечение строк из завершенного отчета

Содержимое завершенной операции запуска отчета можно получить с помощью метода agencies.reports.results.fetchRows . Необходимо указать параметр name для результата отчета, который представляет собой имя ресурса из поля reportResult завершенной операции запуска отчета.

В следующем примере выполняется GET запрос для получения строк результатов:

ОТДЫХ

Запрос

curl \
  'https://agenciesandbrands.googleapis.com/v1/agencies/ACCOUNT_ID/reports/123456789/results/10486370264:fetchRows?pageSize=1' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --compressed

Ответ

{
  "rows": [
    {
      "dimensionValues": [
        {
          "stringValue": "2026-08-01"
        },
        {
          "stringValue": "deal-1001"
        },
        {
          "stringValue": "creative-1001"
        }
      ],
      "metricValueGroups": [
        {
          "primaryValues": [
            {
              "intValue": "500000"
            },
            {
              "intValue": "450000"
            },
            {
              "intValue": "150000"
            },
            {
              "intValue": "150000"
            },
            {
              "intValue": "3200"
            },
            {
              "doubleValue": 450.75
            },
            {
              "doubleValue": 405.67
            }
          ]
        }
      ]
    }
  ],
  "runTime": "2026-08-05T12:00:00Z",
  "dateRanges": [
    {
      "startDate": {
        "year": 2026,
        "month": 7,
        "day": 6
      },
      "endDate": {
        "year": 2026,
        "month": 8,
        "day": 4
      }
    }
  ],
  "totalRowCount": 2,
  "nextPageToken": "QC7nzW91c2VTcGFubmVyQ29udGlubWF0aW6uVG9wZY45NP=="
}

Java

/*
 * Copyright (c) 2026 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */

package com.google.api.services.samples.agenciesandbrands.v1.agencies.reports.results;

import com.google.api.services.agenciesandbrands.v1.AgenciesAndBrands;
import com.google.api.services.agenciesandbrands.v1.model.FetchReportResultRowsResponse;
import com.google.api.services.samples.agenciesandbrands.v1.Utils;
import java.io.IOException;
import java.security.GeneralSecurityException;
import net.sourceforge.argparse4j.ArgumentParsers;
import net.sourceforge.argparse4j.inf.ArgumentParser;
import net.sourceforge.argparse4j.inf.ArgumentParserException;
import net.sourceforge.argparse4j.inf.Namespace;

public class FetchReportResultRows {

  /**
   * Executes the fetchRows operation for report result rows.
   *
   * @param agenciesAndBrandsClient the initialized Agencies & Brands API client.
   * @param accountId the account ID of the agency.
   * @param reportId the resource ID of the report.
   * @param resultId the resource ID of the report result.
   * @param pageSize the maximum number of rows to return per page.
   * @param pageToken the page token from a previous response, if any.
   * @throws IOException if the API returns an error.
   */
  public static void execute(
      AgenciesAndBrands agenciesAndBrandsClient,
      Long accountId,
      String reportId,
      String resultId,
      Integer pageSize,
      String pageToken)
      throws IOException {
    String name = String.format("agencies/%s/reports/%s/results/%s", accountId, reportId, resultId);

    System.out.printf("Fetching report result rows for \"%s\".%n", name);

    AgenciesAndBrands.Agencies.Reports.Results.FetchRows request =
        agenciesAndBrandsClient.agencies().reports().results().fetchRows(name);

    if (pageSize != null) {
      request.setPageSize(pageSize);
    }
    if (pageToken != null) {
      request.setPageToken(pageToken);
    }

    FetchReportResultRowsResponse response = request.execute();

    System.out.println("Successfully fetched report result rows:");
    Utils.jsonPrettyPrint(response);
  }

  /**
   * Creates and configures the ArgumentParser for this sample.
   *
   * @return the configured ArgumentParser.
   */
  private static ArgumentParser createArgumentParser() {
    ArgumentParser parser =
        ArgumentParsers.newFor("FetchReportResultRows")
            .build()
            .defaultHelp(true)
            .description("Fetches rows for a completed report result.");

    // Required arguments.
    parser
        .addArgument("-a", "--account_id")
        .help("The account ID of the agency.")
        .required(true)
        .type(Long.class);
    parser
        .addArgument("-r", "--report_id")
        .help("The resource ID of the report.")
        .required(true);
    parser
        .addArgument("--result_id")
        .help("The resource ID of the report result. This is identical to the resource ID of " +
            "the corresponding report run operation.")
        .required(true);

    // Optional arguments.
    parser
        .addArgument("--page_size")
        .help("The maximum number of rows to return per page.")
        .type(Integer.class);
    parser
        .addArgument("--page_token")
        .help("A page token, received from a previous `FetchReportResultRows` call.");

    return parser;
  }

  public static void main(String[] args) {
    ArgumentParser parser = createArgumentParser();

    Namespace parsedArgs = null;
    try {
      parsedArgs = parser.parseArgs(args);
    } catch (ArgumentParserException ex) {
      parser.handleError(ex);
      System.exit(1);
    }

    AgenciesAndBrands client = null;
    try {
      client = Utils.getAgenciesAndBrandsClient();
    } catch (IOException ex) {
      System.out.printf("Unable to create Agencies & Brands API service:%n%s", ex);
      System.out.println("Did you specify a valid path to a service account key file?");
      System.exit(1);
    } catch (GeneralSecurityException ex) {
      System.out.printf("Unable to establish secure HttpTransport:%n%s", ex);
      System.exit(1);
    }

    try {
      execute(
          client,
          parsedArgs.getLong("account_id"),
          parsedArgs.getString("report_id"),
          parsedArgs.getString("result_id"),
          parsedArgs.getInt("page_size"),
          parsedArgs.getString("page_token"));
    } catch (IOException ex) {
      System.out.printf("Agencies & Brands API returned error response:%n%s", ex);
      System.exit(1);
    }
  }
}

Вы можете указать следующие параметры запроса:

pageSize : максимальное количество возвращаемых строк. Значение по умолчанию — 1000 строк, максимальное — 10 000 строк.
pageToken : токен страницы, возвращенный в предыдущем ответе fetchRows , для получения следующей партии строк.

Ответ содержит следующие поля:

rows : Массив объектов Row . Каждая строка содержит:
- dimensionValues : Значения для каждого запрошенного измерения, упорядоченные так же, как и измерения в определении отчета.
- metricValueGroups : Группы значений метрик, соответствующие диапазонам дат. Каждая группа содержит список primaryValues упорядоченный так же, как и метрики в определении отчета.
dateRanges : Вычисляемые фиксированные диапазоны дат для отчета. Поле dateRanges включается только в текст ответа на первой странице.
totalRowCount : Общее количество строк в результатах отчета. Поле totalRowCount включается только в тело ответа на первой странице.
nextPageToken : Токен, передаваемый в последующих запросах для получения следующей страницы строк. Если дополнительных строк нет, API Agencies & Brands пропускает это поле в теле ответа.

В примере REST agencies.reports.results.fetchRows каждый элемент в поле rows напрямую соответствует ReportDefinition , настроенному в отчете:

dimensionValues : содержит значения, соответствующие каждому измерению в поле reportDefinition.dimensions , в точно указанном вами порядке. В примере первое значение, 2026-08-01 , соответствует измерению DATE , второе значение, deal-1001 , соответствует измерению DEAL_ID , а третье значение, creative-1001 , соответствует измерению CREATIVE_ID .
metricValueGroups : содержит значения метрик, сгруппированные по диапазонам дат отчета. В каждой группе поле primaryValues содержит значения, соответствующие каждой метрике в поле reportDefinition.metrics , в точном порядке, указанном вами. В этом примере семь значений соответствуют следующим значениям перечисления Metric :
- BIDS : 500000
- BIDS_IN_AUCTION : 450000
- AUCTIONS_WON : 150000
- IMPRESSIONS : 150000
- CLICKS : 3200
- SPEND : 450.75
- SPEND_WITHOUT_CURATION_PARTNER_FEE : 405.67
dateRanges : содержит фиксированный диапазон дат, вычисленный Google для относительного диапазона THIS_MONTH_TO_DATE , заданного в определении отчета.

Следующие шаги

Узнайте, как создавать и изменять отчеты с помощью API агентств и брендов.
Узнайте, как просматривать существующие отчеты с помощью API агентств и брендов.
Узнайте, как создавать отчеты с помощью API агентств и брендов.

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

Прежде чем начать

Статус опроса запущенного отчета

ОТДЫХ

Запрос

Ответ

Java

Извлечение строк из завершенного отчета

ОТДЫХ

Запрос

Ответ

Java

Следующие шаги

Проведите опрос и просмотрите готовые отчеты.