איך יוצרים סקר וצופים בדוחות שהושלמו

פעולת הרצת דוח מתבצעת באופן אסינכרוני כפעולה ממושכת, שמיוצגת על ידי האובייקט 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: מזהה החשבון.
  • ‫ACCESS_TOKEN: אסימון הגישה.

תשובה

אם הפעולה הושלמה בהצלחה, התגובה היא Operation עם השדה done שמוגדר לערך true, והמטען הייעודי (payload) 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 שמתאר למה הפעלת הדוח נכשלה.

אחזור שורות מדוח שהושלם

אפשר לאחזר את התוכן של פעולת הפקת דוח שהושלמה באמצעות השיטה 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: אסימון שמעבירים בבקשות הבאות כדי לאחזר את הדף הבא של השורות. אם אין שורות נוספות, ה-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, בדיוק לפי הסדר שציינתם. בדוגמה הזו, ארבעת הערכים תואמים לערכי ה-enum הבאים Metric:

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

  • ‫dateRanges: מכיל את טווח התאריכים הקבוע ש-Google חישבה עבור הטווח היחסי, THIS_MONTH_TO_DATE, שהוגדר בהגדרת הדוח.

השלבים הבאים