Pesquisar e acessar relatórios concluídos

Uma operação de execução de relatório é executada de forma assíncrona como uma operação de longa duração, representada pelo Operation objeto. A saída de uma operação de execução de relatório são resultados com base no Report objeto.

Este guia descreve como usar a API Curation Partners para obter uma operação de execução de relatório para consultar o status da operação, e buscar os resultados da operação de execução de relatório concluída.

Importante: as operações de execução de relatório e os resultados correspondentes têm um período de armazenamento de sete dias. Após o período de armazenamento, a API Curation Partners retorna uma resposta de erro se você sondar a operação de execução de relatório ou buscar os resultados do relatório.

Antes de começar

Antes de continuar, conclua as etapas a seguir:

• Configure a autenticação.
• Inicie uma execução de relatório para receber um nome de recurso de operação de longa duração.

Consultar o status de uma execução de relatório

Para verificar o status de execução de uma operação de execução de relatório, use o curators.reports.operations.get método.

O exemplo a seguir faz uma solicitação GET para consultar uma operação:

REST

Solicitação

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

Substitua:

• ACCOUNT_ID: seu ID da conta.
• ACCESS_TOKEN: seu token de acesso.

Resposta

Quando concluída, a resposta é uma Operation com o campo done definido como true, e o payload response é preenchido com o nome do recurso reportResult:

{
  "name": "curators/ACCOUNT_ID/reports/123456789/operations/10486370264",
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.ads.curationpartners.v1.RunReportMetadata",
    "percentComplete": 100
  },
  "response": {
    "@type": "type.googleapis.com/google.ads.curationpartners.v1.RunReportResponse",
    "reportResult": "curators/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.curationpartners.v1.curators.reports.operations;

import com.google.api.services.curationpartners.v1.CurationPartners;
import com.google.api.services.curationpartners.v1.model.Operation;
import com.google.api.services.samples.curationpartners.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 curationPartnersClient the initialized Curation Partners API client.
   * @param accountId the account ID of the curator.
   * @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(
      CurationPartners curationPartnersClient,
      Long accountId,
      String reportId,
      String operationId)
      throws IOException {
    String name =
        String.format(
            "curators/%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 =
        curationPartnersClient
            .curators()
            .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 " +
                "`curators.reports.results.fetchRows` method.");

    // Required arguments.
    parser
        .addArgument("-a", "--account_id")
        .help("The account ID of the curator.")
        .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);
    }

    CurationPartners client = null;
    try {
      client = Utils.getCurationPartnersClient();
    } catch (IOException ex) {
      System.out.printf("Unable to create Curation Partners 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("Curation Partners API returned error response:%n%s", ex);
      System.exit(1);
    }
  }
}

A seguir, descrevemos como usar o campo done para consultar o status da operação:

• Se o campo done na resposta for o valor false, a operação de execução de relatório ainda estará em processamento.
• Se o campo done na resposta for o valor true, a operação de execução de relatório será concluída. O objeto Operation no corpo da resposta também contém um dos seguintes campos:
  • response: indica que a operação de execução de relatório foi bem-sucedida. Esse campo é um objeto preenchido com um campo @type definido como o tipo type.googleapis.com/google.ads.curationpartners.v1.RunReportResponse. O tipo RunReportResponse é preenchido com um campo reportResult que contém o nome do relatório correspondente result.
  • error: indica que a operação de execução de relatório não foi bem-sucedida. O campo error é preenchido com um Status objeto que descreve por que a execução do relatório falhou.

Ponto principal: o Google recomenda sondar com um algoritmo de espera exponencial começando com uma duração de 30 segundos.

Dica: O campo metadata da operação é preenchido com @type definido como RunReportMetadata. Você pode usar o campo percentComplete para receber uma estimativa de quão perto a operação de execução de relatório está de ser concluída. Se o campo percentComplete não estiver preenchido, a porcentagem de conclusão estimada para a execução do relatório será de 0%.

Buscar linhas de um relatório concluído

É possível recuperar o conteúdo de uma operação de execução de relatório concluída com o curators.reports.results.fetchRows método. Você precisa preencher o parâmetro de caminho name para o resultado do relatório, que é o nome do recurso do campo reportResult de uma operação de execução de relatório concluída.

O exemplo a seguir faz uma solicitação GET para buscar linhas de resultado:

REST

Solicitação

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

Resposta

{
  "rows": [
    {
      "dimensionValues": [
        {
          "stringValue": "2026-08-01"
        },
        {
          "stringValue": "segment-1001"
        }
      ],
      "metricValueGroups": [
        {
          "primaryValues": [
            {
              "intValue": "150000"
            },
            {
              "intValue": "3200"
            },
            {
              "doubleValue": 450.75
            },
            {
              "doubleValue": 45.08
            }
          ]
        }
      ]
    }
  ],
  "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.curationpartners.v1.curators.reports.results;

import com.google.api.services.curationpartners.v1.CurationPartners;
import com.google.api.services.curationpartners.v1.model.FetchReportResultRowsResponse;
import com.google.api.services.samples.curationpartners.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 curationPartnersClient the initialized Curation Partners API client.
   * @param accountId the account ID of the curator.
   * @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(
      CurationPartners curationPartnersClient,
      Long accountId,
      String reportId,
      String resultId,
      Integer pageSize,
      String pageToken)
      throws IOException {
    String name = String.format("curators/%s/reports/%s/results/%s", accountId, reportId, resultId);

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

    CurationPartners.Curators.Reports.Results.FetchRows request =
        curationPartnersClient.curators().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 curator.")
        .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);
    }

    CurationPartners client = null;
    try {
      client = Utils.getCurationPartnersClient();
    } catch (IOException ex) {
      System.out.printf("Unable to create Curation Partners 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("Curation Partners API returned error response:%n%s", ex);
      System.exit(1);
    }
  }
}

É possível especificar os seguintes parâmetros de consulta:

• pageSize: o número máximo de linhas a serem retornadas. O padrão é de 1.000 linhas, e o máximo é de 10.000 linhas.
• pageToken: o token de página retornado em uma resposta fetchRows anterior para buscar o próximo lote de linhas.

A resposta contém os seguintes campos:

• rows: uma matriz de objetos Row. Cada linha contém:
  • dimensionValues: valores para cada dimensão solicitada, ordenados de forma idêntica às dimensões na definição do relatório.
  • metricValueGroups: grupos de valores de métricas correspondentes aos períodos. Cada grupo contém uma lista primaryValues ordenada de forma idêntica às métricas na definição do relatório.
• dateRanges: os períodos fixos calculados para o relatório. O campo dateRanges só é incluído no corpo da resposta da primeira página.
• totalRowCount: o número total de linhas no resultado do relatório. O campo totalRowCount só é incluído no corpo da resposta da primeira página.
• nextPageToken: token a ser transmitido em solicitações subsequentes para recuperar a próxima página de linhas. Se não houver mais linhas, a API Curation Partners vai omitir esse campo do corpo da resposta.

No exemplo de REST curators.reports.results.fetchRows, cada item em rows é mapeado diretamente para o ReportDefinition configurado no relatório:

• dimensionValues: contém valores correspondentes a cada dimensão no campo reportDefinition.dimensions na ordem exata especificada. No exemplo, o primeiro valor 2026-08-01 corresponde à dimensão DATE, e o segundo valor, segment-1001, corresponde à dimensão CURATION_DATA_SEGMENT_ID.

• metricValueGroups: contém valores de métricas agrupados nos períodos do relatório. Em cada grupo, o campo primaryValues contém os valores correspondentes a cada métrica no campo reportDefinition.metrics na ordem exata especificada. Neste exemplo, os quatro valores correspondem aos seguintes valores de enumeração Metric:

  • IMPRESSIONS: 150000
  • CLICKS: 3200
  • SPEND: 450.75
  • CURATION_PARTNER_FEE: 45.08

• dateRanges: contém o período fixo que o Google calculou para o período relativo, THIS_MONTH_TO_DATE, configurado na definição do relatório.

Próximas etapas

• Aprenda a criar e modificar relatórios com a API Curation Partners.
• Aprenda a visualizar relatórios atuais com a API Curation Partners.
• Aprenda a gerar relatórios com a API Curation Partners.