إجراء استطلاع وعرض التقارير المكتملة

يتم تنفيذ عملية تشغيل التقرير بشكل غير متزامن كعملية طويلة الأمد، ويتم تمثيلها باستخدام العنصر 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، ويتم ملء حمولة 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 بحقل 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=="
}

جافا

/*
 * 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 التالية:

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

  • ‫dateRanges: يحتوي على النطاق الزمني الثابت الذي احتسبته Google للنطاق النسبي THIS_MONTH_TO_DATE الذي تم إعداده في تعريف التقرير.

الخطوات التالية