Interroger et afficher les rapports terminés

Une opération d'exécution de rapport s'exécute de manière asynchrone en tant qu'opération de longue durée, représentée par l' Operation objet. La sortie d'une opération d'exécution de rapport correspond aux résultats du rapport basés sur l' Report objet.

Ce guide explique comment utiliser l'API Curation Partners pour qu'une opération d'exécution de rapport interroge l'état de l'opération, et récupère les résultats du rapport une fois l'opération d'exécution de rapport terminée.

Avant de commencer

Avant de continuer, vous devez effectuer les opérations suivantes :

Interroger l'état d'une exécution de rapport

Pour vérifier l'état d'exécution d'une opération d'exécution de rapport, utilisez la curators.reports.operations.get méthode.

L'exemple suivant effectue une requête GET pour interroger une opération :

REST

Requête

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

Remplacez les éléments suivants :

  • ACCOUNT_ID : votre ID de compte.
  • ACCESS_TOKEN : votre jeton d'accès.

Réponse

Une fois l'opération terminée, la réponse est une Operation dont le champ done est défini sur true, et la charge utile response est renseignée avec le nom de ressource 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);
    }
  }
}

La section suivante explique comment utiliser le champ done pour interroger l'état de l'opération :

  • Si le champ done de la réponse est défini sur false, l'opération d'exécution de rapport est toujours en cours de traitement.
  • Si le champ done de la réponse est défini sur true, l'opération d'exécution de rapport est terminée. L'objet Operation du corps de la réponse contient également l'un des champs suivants :
    • response : indique que l'opération d'exécution de rapport a réussi. Ce champ est un objet renseigné avec un champ @type défini sur le type type.googleapis.com/google.ads.curationpartners.v1.RunReportResponse. Le type RunReportResponse est renseigné avec un champ reportResult contenant le nom du rapport correspondant result.
    • error : indique que l'opération d'exécution de rapport n'a pas réussi. Le champ error est renseigné avec un Status objet décrivant la raison de l'échec de l'exécution du rapport.

Récupérer des lignes à partir d'un rapport terminé

Vous pouvez récupérer le contenu d'une opération d'exécution de rapport terminée à l'aide de la curators.reports.results.fetchRows méthode. Vous devez renseigner le paramètre de chemin d'accès name pour le résultat du rapport, qui correspond au nom de ressource du champ reportResult d'une opération d'exécution de rapport terminée.

L'exemple suivant effectue une requête GET pour récupérer les lignes de résultat :

REST

Requête

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

Réponse

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

Vous pouvez spécifier les paramètres de requête suivants :

  • pageSize : nombre maximal de lignes à renvoyer. La valeur par défaut est de 1 000 lignes, et la valeur maximale est de 10 000 lignes.
  • pageToken: jeton de page renvoyé dans une réponse fetchRows précédente pour récupérer le lot de lignes suivant.

La réponse contient les champs suivants :

  • rows: tableau d'objets Row. Chaque ligne contient les éléments suivants :
    • dimensionValues: valeurs de chaque dimension demandée, classées de manière identique aux dimensions de la définition du rapport.
    • metricValueGroups: groupes de valeurs de métriques correspondant aux plages de dates. Chaque groupe contient une liste primaryValues classée de manière identique aux métriques de la définition du rapport.
  • dateRanges: plages de dates fixes calculées pour le rapport. Le champ dateRanges n'est inclus dans le corps de la réponse que pour la première page.
  • totalRowCount: nombre total de lignes dans le résultat du rapport. Le champ totalRowCount n'est inclus dans le corps de la réponse que pour la première page.
  • nextPageToken: jeton à transmettre dans les requêtes suivantes pour récupérer la page de lignes suivante. Si aucune ligne supplémentaire n'existe, l'API Curation Partners omet ce champ du corps de la réponse.

Dans l'exemple REST curators.reports.results.fetchRows, chaque élément de rows correspond directement à la ReportDefinition configurée dans le rapport :

  • dimensionValues: contient les valeurs correspondant à chaque dimension du champ reportDefinition.dimensions, dans l'ordre exact que vous avez spécifié. Dans l'exemple, la première valeur 2026-08-01 correspond à la dimension DATE, et la deuxième valeur, segment-1001, correspond à la dimension CURATION_DATA_SEGMENT_ID.

  • metricValueGroups: contient les valeurs de métriques regroupées dans les plages de dates du rapport. Dans chaque groupe, le champ primaryValues contient les valeurs correspondant à chaque métrique du champ reportDefinition.metrics, dans l'ordre exact que vous avez spécifié. Dans cet exemple, les quatre valeurs correspondent aux valeurs d'énumération Metric suivantes :

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

  • dateRanges: contient la plage de dates fixe que Google a calculée pour la plage relative, THIS_MONTH_TO_DATE, configurée dans la définition du rapport.

Étapes suivantes