发起投票并查看已完成的报告

报告运行操作会作为长时间运行的操作异步执行， 由 Operation 对象表示。报告运行操作的输出是基于 Report 对象的报告结果。

本指南介绍了如何使用 Curation Partners API 来 获取报告运行操作，以轮询操作的状态， 并提取已完成的报告运行 操作的报告结果。

重要提示： 报告运行操作及其相应结果的保留期限均为 7 天。如果保留期限过后，您轮询报告运行操作或提取报告结果， Curation Partners API 会返回错误响应。

准备工作

在继续之前，您必须完成以下操作：

• 设置身份验证。
• 启动报告运行 以获取长时间运行的操作资源名称。

轮询报告运行的状态

如需检查报告运行操作的执行状态，请使用 curators.reports.operations.get 方法。

以下示例会发出 GET 请求来轮询操作：

REST

请求

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

替换以下内容：

• ACCOUNT_ID：您的账号 ID。
• ACCESS_TOKEN：您的访问令牌。

响应

成功完成后，响应将是一个 Operation，其中 done 字段设置为 true，并且 response 有效负载填充了 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);
    }
  }
}

下面介绍了如何使用 done 字段轮询操作的状态：

• 如果响应中的 done 字段的值为 false，则表示报告运行操作仍在处理中。
• 如果响应中的 done 字段的值为 true，则表示报告运行操作已完成。响应正文中的 Operation 对象还包含以下任一字段：
  • response：表示报告运行操作成功。 此字段是一个对象，其中填充了 @type 字段，该字段设置为 type.googleapis.com/google.ads.curationpartners.v1.RunReportResponse 类型。RunReportResponse 类型填充了 reportResult 字段，其中包含相应报告 result的名称。
  • error：表示报告运行操作未成功。 error 字段填充了一个 Status 对象，用于说明报告运行失败的原因。

要点： Google 建议使用指数退避算法进行轮询， 初始时长为 30 秒。

提示： 操作的 metadata 字段填充了 @type，该字段设置为 RunReportMetadata。您可以使用 percentComplete 字段来估算报告运行操作的完成进度。如果 percentComplete 字段未填充，则报告运行的估计完成 百分比为 0%。

从已完成的报告中提取行

您可以使用 curators.reports.results.fetchRows 方法检索已完成的报告运行操作的内容。您必须填写报告结果的 name 路径参数，该参数是完整报告运行操作的 reportResult 字段中的资源名称。

以下示例会发出 GET 请求来提取结果行：

REST

请求

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

响应

{
  "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);
    }
  }
}

您可以指定以下查询参数：

• pageSize：要返回的最大行数。默认值为 1,000 行，最大值为 10,000 行。
• pageToken：在之前的 fetchRows 响应中返回的页面令牌，用于提取下一批行。

响应包含以下字段：

• rows：Row 对象数组。每行包含：
  • dimensionValues：每个请求的维度的值，其顺序与报告定义中的维度相同。
  • metricValueGroups：与日期范围对应的指标值组。每个组都包含一个 primaryValues 列表，其顺序与报告定义中的指标相同。
• dateRanges：报告的计算固定日期范围。dateRanges 字段仅包含在第一页的响应正文中。
• totalRowCount：报告结果中的总行数。totalRowCount 字段仅包含在第一页的响应正文中。
• nextPageToken：要在后续请求中传递的令牌，用于检索下一页的行。 如果没有其他行，Curation Partners API 会从响应正文中省略此字段。

在 curators.reports.results.fetchRows REST 示例中，rows 中的每个项都直接映射到报告中配置的 ReportDefinition：

• dimensionValues：包含与 reportDefinition.dimensions 字段中的每个维度对应的值，其顺序与您指定的顺序完全相同。 在示例中，第一个值 2026-08-01 对应于 DATE 维度，第二个值 segment-1001 对应于 CURATION_DATA_SEGMENT_ID 维度。

• metricValueGroups：包含按报告的日期范围分组的指标值。在每个组中，primaryValues 字段包含与 reportDefinition.metrics 字段中的每个指标对应的值，其顺序与您指定的顺序完全相同。在此示例中，这四个值对应于以下 Metric 枚举值：

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

• dateRanges：包含 Google 为报告定义中配置的相对范围 THIS_MONTH_TO_DATE 计算的固定日期范围。

后续步骤

• 了解如何使用 Curation Partners API 创建和修改报告。
• 了解如何使用 Curation Partners API 查看现有报告。
• 了解如何运行报告 使用 Curation Partners API。