완료된 보고서 폴링 및 보기

보고서 실행 작업은 장기 실행 작업으로 비동기식으로 실행됩니다. 다음에 의해 표시됩니다. Operation 객체. 보고서 실행 작업의 출력은 보고서 결과입니다. 기반으로 하는 Report 객체.

이 가이드에서는 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: 액세스 토큰

응답

성공적으로 완료되면 응답은 done 필드가 true로 설정된 Operation이고 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"
  }
}

자바

/*
 * 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 유형은 해당 보고서 result의 이름이 포함된 reportResult 필드로 채워집니다.
    • error: 보고서 실행 작업이 성공하지 못했음을 나타냅니다. error 필드는 보고서 실행이 실패한 이유를 설명하는 Status 객체로 채워집니다.

완료된 보고서에서 행 가져오기

curators.reports.results.fetchRows 메서드를 사용하여 완료된 보고서 실행 작업의 콘텐츠를 가져올 수 있습니다. 완료된 보고서 실행 작업의 reportResult 필드에 있는 리소스 이름인 보고서 결과의 name 경로 매개변수를 입력해야 합니다.

다음 예에서는 결과 행을 가져오기 위해 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=="
}

자바

/*
 * 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 enum 값에 해당합니다.

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

  • dateRanges: 보고서 정의에 구성된 상대적 범위 THIS_MONTH_TO_DATE에 대해 Google에서 계산한 고정 기간을 포함합니다.

다음 단계