Umfragen durchführen und abgeschlossene Berichte ansehen

Ein Berichtsausführungsvorgang wird asynchron als Vorgang mit langer Ausführungszeit ausgeführt, dargestellt durch das Operation Objekt. Die Ausgabe eines Berichtsausführungsvorgangs sind Berichtsergebnisse, die auf dem Report Objekt basieren.

In diesem Leitfaden wird beschrieben, wie Sie mit der Curation Partners API einen Berichtsausführungsvorgang verwenden können, um den Status des Vorgangs abzurufen und die Berichtsergebnisse des abgeschlossenen Berichtsausführungs vorgangs abzurufen.

Hinweis

Bevor Sie fortfahren, müssen Sie Folgendes tun:

Status einer Berichtsausführung abrufen

Verwenden Sie die curators.reports.operations.get Methode, um den Ausführungsstatus eines Berichtsausführungsvorgangs zu prüfen.

Im folgenden Beispiel wird eine GET-Anfrage gesendet, um einen Vorgang abzurufen:

REST

Anfrage

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

Ersetzen Sie Folgendes:

  • ACCOUNT_ID: Ihre Konto-ID.
  • ACCESS_TOKEN: Ihr Zugriffstoken.

Antwort

Wenn der Vorgang erfolgreich abgeschlossen wurde, ist die Antwort ein Operation-Objekt, bei dem das Feld done auf true gesetzt ist. Die response-Nutzlast enthält den Ressourcennamen 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);
    }
  }
}

Im Folgenden wird beschrieben, wie Sie das Feld done verwenden können, um den Status des Vorgangs abzurufen:

  • Wenn das Feld done in der Antwort den Wert false hat, wird der Berichtsausführungsvorgang noch verarbeitet.
  • Wenn das Feld done in der Antwort den Wert true hat, ist der Berichtsausführungsvorgang abgeschlossen. Das Operation-Objekt im Antworttext enthält außerdem eines der folgenden Felder:
    • response: Gibt an, dass der Berichtsausführungsvorgang erfolgreich war. Dieses Feld ist ein Objekt, das mit einem Feld @type gefüllt ist, das auf den Typ type.googleapis.com/google.ads.curationpartners.v1.RunReportResponse gesetzt ist. Der RunReportResponse Typ enthält ein reportResult Feld mit dem Namen des entsprechenden Berichts result.
    • error: Gibt an, dass der Berichtsausführungsvorgang nicht erfolgreich war. Das error Feld enthält ein Status Objekt, in dem beschrieben wird, warum die Berichtsausführung fehlgeschlagen ist.

Zeilen aus einem abgeschlossenen Bericht abrufen

Mit der curators.reports.results.fetchRows Methode können Sie die Inhalte eines abgeschlossenen Berichtsausführungsvorgangs abrufen. Sie müssen den Pfad-Parameter name für das Berichtsergebnis angeben. Das ist der Ressourcenname aus dem Feld reportResult eines abgeschlossenen Berichtsausführungsvorgangs.

Im folgenden Beispiel wird eine GET-Anfrage gesendet, um Ergebniszeilen abzurufen:

REST

Anfrage

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

Antwort

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

Sie können die folgenden Abfrageparameter angeben:

  • pageSize: Die maximale Anzahl der zurückzugebenden Zeilen. Der Standardwert ist 1.000 Zeilen und der Höchstwert 10.000 Zeilen.
  • pageToken: Das Seitentoken, das in einer vorherigen fetchRows-Antwort zurückgegeben wurde, um den nächsten Batch von Zeilen abzurufen.

Die Antwort umfasst die folgenden Felder:

  • rows: Ein Array von Row-Objekten. Jede Zeile enthält:
    • dimensionValues: Werte für jede angeforderte Dimension, in derselben Reihenfolge wie die Dimensionen in der Berichtsdefinition.
    • metricValueGroups: Gruppen von Messwertwerten, die den Zeiträumen entsprechen. Jede Gruppe enthält eine Liste primaryValues, die in derselben Reihenfolge wie die Messwerte in der Berichtsdefinition angeordnet ist.
  • dateRanges: Die berechneten festen Zeiträume für den Bericht. Das Feld dateRanges ist nur im Antworttext der ersten Seite enthalten.
  • totalRowCount: Die Gesamtzahl der Zeilen im Berichtsergebnis. Das Feld totalRowCount ist nur im Antworttext der ersten Seite enthalten.
  • nextPageToken: Token, das in nachfolgenden Anfragen übergeben werden muss, um die nächste Seite mit Zeilen abzurufen. Wenn keine weiteren Zeilen vorhanden sind, wird dieses Feld von der Curation Partners API aus dem Antworttext entfernt.

Im REST-Beispiel curators.reports.results.fetchRows entspricht jedes Element in rows direkt der in der Berichtsdefinition konfigurierten ReportDefinition:

  • dimensionValues: Enthält Werte, die jeder Dimension im Feld reportDefinition.dimensions entsprechen, in der von Ihnen angegebenen Reihenfolge. Im Beispiel entspricht der erste Wert 2026-08-01 der Dimension DATE und der zweite Wert segment-1001 der Dimension CURATION_DATA_SEGMENT_ID.

  • metricValueGroups: Enthält Messwertwerte, die in den Zeiträumen des Berichts gruppiert sind. In jeder Gruppe enthält das Feld primaryValues die Werte, die den einzelnen Messwerten im Feld reportDefinition.metrics entsprechen, in der von Ihnen angegebenen Reihenfolge. In diesem Beispiel entsprechen die vier Werte den folgenden Metric-Enum-Werten:

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

  • dateRanges: Enthält den festen Zeitraum, den Google für den relativen Zeitraum THIS_MONTH_TO_DATE berechnet hat, der in der Berichtsdefinition konfiguriert ist.

Nächste Schritte