Membuat polling dan melihat laporan yang telah selesai

Operasi menjalankan laporan dieksekusi secara asinkron sebagai operasi yang berjalan lama, direpresentasikan oleh Operation objek. Output operasi menjalankan laporan adalah hasil laporan berdasarkan objek Report.

Panduan ini menjelaskan cara menggunakan Curation Partners API untuk mendapatkan operasi menjalankan laporan guna melakukan polling status operasi, dan mengambil hasil laporan dari operasi menjalankan laporan yang telah selesai.

Sebelum memulai

Sebelum melanjutkan, Anda harus menyelesaikan hal berikut:

Melakukan polling status menjalankan laporan

Untuk memeriksa status eksekusi operasi menjalankan laporan, gunakan metode curators.reports.operations.get.

Contoh berikut membuat permintaan GET untuk melakukan polling operasi:

REST

Permintaan

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

Ganti kode berikut:

  • ACCOUNT_ID: ID akun Anda.
  • ACCESS_TOKEN: token akses Anda.

Respons

Jika berhasil diselesaikan, responsnya adalah Operation dengan kolom done yang ditetapkan ke true, dan payload response diisi dengan nama resource 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);
    }
  }
}

Berikut ini dijelaskan cara menggunakan kolom done untuk melakukan polling status operasi:

  • Jika kolom done dalam respons adalah nilai false, operasi menjalankan laporan masih diproses.
  • Jika kolom done dalam respons adalah nilai true, operasi menjalankan laporan telah selesai. Objek Operation dalam isi respons juga berisi salah satu kolom berikut:
    • response: Menunjukkan bahwa operasi menjalankan laporan berhasil. Kolom ini adalah objek yang diisi dengan kolom @type yang ditetapkan ke jenis type.googleapis.com/google.ads.curationpartners.v1.RunReportResponse. Jenis RunReportResponse diisi dengan reportResult kolom yang berisi nama laporan yang sesuai result.
    • error: Menunjukkan bahwa operasi menjalankan laporan tidak berhasil. Kolom error diisi dengan objek Status yang menjelaskan alasan operasi menjalankan laporan gagal.

Mengambil baris dari laporan yang telah selesai

Anda dapat mengambil konten operasi menjalankan laporan yang telah selesai dengan metode curators.reports.results.fetchRows. Anda harus mengisi parameter jalur name untuk hasil laporan, yang merupakan nama resource dari kolom reportResult operasi menjalankan laporan yang telah selesai.

Contoh berikut membuat permintaan GET untuk mengambil baris hasil:

REST

Permintaan

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

Respons

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

Anda dapat menentukan parameter kueri berikut:

  • pageSize: jumlah maksimum baris yang akan ditampilkan. Nilai default-nya adalah 1.000 baris, dan maksimumnya adalah 10.000 baris.
  • pageToken: token halaman yang ditampilkan dalam respons fetchRows sebelumnya untuk mengambil batch baris berikutnya.

Respons berisi kolom berikut:

  • rows: Array objek Row. Setiap baris berisi:
    • dimensionValues: Nilai untuk setiap dimensi yang diminta, diurutkan secara identik dengan dimensi dalam definisi laporan.
    • metricValueGroups: Grup nilai metrik yang sesuai dengan rentang tanggal. Setiap grup berisi daftar primaryValues yang diurutkan secara identik dengan metrik dalam definisi laporan.
  • dateRanges: Rentang tanggal tetap yang dihitung untuk laporan. Kolom dateRanges hanya disertakan dalam isi respons halaman pertama.
  • totalRowCount: Jumlah total baris dalam hasil laporan. Kolom totalRowCount hanya disertakan dalam isi respons halaman pertama.
  • nextPageToken: Token yang akan diteruskan dalam permintaan berikutnya untuk mengambil baris halaman berikutnya. Jika tidak ada baris tambahan, Curation Partners API akan menghapus kolom ini dari isi respons.

Dalam contoh REST curators.reports.results.fetchRows, setiap item dalam rows dipetakan langsung ke ReportDefinition yang dikonfigurasi dalam laporan:

  • dimensionValues: berisi nilai yang sesuai dengan setiap dimensi di kolom reportDefinition.dimensions dalam urutan yang sama persis dengan yang Anda tentukan. Dalam contoh ini, nilai pertama 2026-08-01 sesuai dengan dimensi DATE, dan nilai kedua, segment-1001, sesuai dengan dimensi CURATION_DATA_SEGMENT_ID.

  • metricValueGroups: berisi nilai metrik yang dikelompokkan dalam rentang tanggal laporan. Di setiap grup, kolom primaryValues berisi nilai yang sesuai dengan setiap metrik di kolom reportDefinition.metrics dalam urutan yang sama persis dengan yang Anda tentukan. Dalam contoh ini, keempat nilai tersebut sesuai dengan nilai enum Metric berikut:

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

  • dateRanges: berisi rentang tanggal tetap yang dihitung Google untuk rentang relatif, THIS_MONTH_TO_DATE, yang dikonfigurasi dalam definisi laporan.

Langkah berikutnya