نظرسنجی و مشاهده گزارش‌های تکمیل‌شده

یک عملیات اجرای گزارش به صورت ناهمزمان به عنوان یک عملیات طولانی مدت اجرا می‌شود که توسط شیء Operation نمایش داده می‌شود. برای تعیین زمان تکمیل عملیات اجرای گزارش، می‌توانید شیء Operation را با متد agencies.reports.operations.get بررسی کنید.

شما می‌توانید نتایج یک عملیات اجرای گزارش تکمیل‌شده را با متد agencies.reports.results.fetchRows مشاهده کنید. خروجی یک عملیات اجرای گزارش شامل نتایج گزارش بر اساس شیء Report است.

این راهنما نحوه استفاده از API آژانس‌ها و برندها را برای دریافت عملیات اجرای گزارش، نظرسنجی از وضعیت عملیات و دریافت نتایج گزارش از عملیات اجرای گزارش تکمیل‌شده شرح می‌دهد.

قبل از اینکه شروع کنی

قبل از ادامه، باید موارد زیر را تکمیل کنید:

وضعیت نظرسنجی از اجرای گزارش

برای بررسی وضعیت اجرای یک عملیات اجرای گزارش، از متد agencies.reports.operations.get استفاده کنید.

مثال زیر یک درخواست GET برای نظرسنجی از یک عملیات ارسال می‌کند:

استراحت

درخواست 

curl \
  'https://agenciesandbrands.googleapis.com/v1/agencies/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": "agencies/ACCOUNT_ID/reports/123456789/operations/10486370264",
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.ads.agenciesandbrands.v1.RunReportMetadata",
    "percentComplete": 100
  },
  "response": {
    "@type": "type.googleapis.com/google.ads.agenciesandbrands.v1.RunReportResponse",
    "reportResult": "agencies/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.agenciesandbrands.v1.agencies.reports.operations;

import com.google.api.services.agenciesandbrands.v1.AgenciesAndBrands;
import com.google.api.services.agenciesandbrands.v1.model.Operation;
import com.google.api.services.samples.agenciesandbrands.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 agenciesAndBrandsClient the initialized Agencies & Brands API client.
   * @param accountId the account ID of the agency.
   * @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(
      AgenciesAndBrands agenciesAndBrandsClient,
      Long accountId,
      String reportId,
      String operationId)
      throws IOException {
    String name =
        String.format(
            "agencies/%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 =
        agenciesAndBrandsClient
            .agencies()
            .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 " +
                "`agencies.reports.results.fetchRows` method.");

    // Required arguments.
    parser
        .addArgument("-a", "--account_id")
        .help("The account ID of the agency.")
        .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);
    }

    AgenciesAndBrands client = null;
    try {
      client = Utils.getAgenciesAndBrandsClient();
    } catch (IOException ex) {
      System.out.printf("Unable to create Agencies & Brands 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("Agencies & Brands API returned error response:%n%s", ex);
      System.exit(1);
    }
  }
}

در ادامه نحوه استفاده از فیلد done برای مشاهده وضعیت عملیات توضیح داده شده است:

  • اگر فیلد done در پاسخ مقدار false داشته باشد، عملیات اجرای گزارش هنوز در حال پردازش است.
  • اگر فیلد done در پاسخ، مقدار true باشد، عملیات اجرای گزارش کامل شده است. شیء Operation در بدنه پاسخ نیز شامل یکی از فیلدهای زیر است:
    • response : نشان می‌دهد که عملیات اجرای گزارش با موفقیت انجام شده است. این فیلد یک شیء است که با فیلد @type که روی نوع type.googleapis.com/google.ads.agenciesandbrands.v1.RunReportResponse تنظیم شده است، پر شده است. نوع RunReportResponse با یک فیلد reportResult حاوی نام result گزارش مربوطه پر شده است.
    • error : نشان می‌دهد که عملیات اجرای گزارش با شکست مواجه شده است. فیلد error با یک شیء Status پر می‌شود که دلیل شکست اجرای گزارش را شرح می‌دهد.

دریافت ردیف‌ها از یک گزارش تکمیل‌شده

شما می‌توانید محتویات یک عملیات اجرای گزارش تکمیل‌شده را با متد agencies.reports.results.fetchRows بازیابی کنید. شما باید پارامتر name path را برای نتیجه گزارش وارد کنید، که نام منبع از فیلد reportResult یک عملیات اجرای گزارش کامل است.

مثال زیر یک درخواست GET برای دریافت ردیف‌های نتیجه ارسال می‌کند:

استراحت

درخواست 

curl \
  'https://agenciesandbrands.googleapis.com/v1/agencies/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": "deal-1001"
        },
        {
          "stringValue": "creative-1001"
        }
      ],
      "metricValueGroups": [
        {
          "primaryValues": [
            {
              "intValue": "500000"
            },
            {
              "intValue": "450000"
            },
            {
              "intValue": "150000"
            },
            {
              "intValue": "150000"
            },
            {
              "intValue": "3200"
            },
            {
              "doubleValue": 450.75
            },
            {
              "doubleValue": 405.67
            }
          ]
        }
      ]
    }
  ],
  "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.agenciesandbrands.v1.agencies.reports.results;

import com.google.api.services.agenciesandbrands.v1.AgenciesAndBrands;
import com.google.api.services.agenciesandbrands.v1.model.FetchReportResultRowsResponse;
import com.google.api.services.samples.agenciesandbrands.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 agenciesAndBrandsClient the initialized Agencies & Brands API client.
   * @param accountId the account ID of the agency.
   * @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(
      AgenciesAndBrands agenciesAndBrandsClient,
      Long accountId,
      String reportId,
      String resultId,
      Integer pageSize,
      String pageToken)
      throws IOException {
    String name = String.format("agencies/%s/reports/%s/results/%s", accountId, reportId, resultId);

    System.out.printf("Fetching report result rows for \"%s\".%n", name);

    AgenciesAndBrands.Agencies.Reports.Results.FetchRows request =
        agenciesAndBrandsClient.agencies().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 agency.")
        .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);
    }

    AgenciesAndBrands client = null;
    try {
      client = Utils.getAgenciesAndBrandsClient();
    } catch (IOException ex) {
      System.out.printf("Unable to create Agencies & Brands 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("Agencies & Brands API returned error response:%n%s", ex);
      System.exit(1);
    }
  }
}

می‌توانید پارامترهای پرس‌وجوی زیر را مشخص کنید:

  • pageSize : حداکثر تعداد ردیف‌هایی که باید برگردانده شوند. مقدار پیش‌فرض ۱۰۰۰ ردیف و حداکثر ۱۰۰۰۰ ردیف است.
  • pageToken : توکن صفحه‌ای که در پاسخ قبلی fetchRows برای واکشی دسته بعدی سطرها برگردانده شده است.

پاسخ شامل فیلدهای زیر است:

  • rows : آرایه‌ای از اشیاء Row . هر ردیف شامل موارد زیر است:
    • dimensionValues : مقادیری برای هر بُعد درخواستی، که دقیقاً مطابق با ابعاد موجود در تعریف گزارش مرتب شده‌اند.
    • metricValueGroups : گروه‌هایی از مقادیر معیار مربوط به محدوده‌های زمانی. هر گروه شامل یک لیست primaryValues است که به طور یکسان با معیارهای موجود در تعریف گزارش مرتب شده‌اند.
  • dateRanges : محدوده‌های تاریخ ثابت محاسبه‌شده برای گزارش. فیلد dateRanges فقط در بدنه پاسخ صفحه اول قرار می‌گیرد.
  • totalRowCount : تعداد کل ردیف‌ها در نتیجه گزارش. فیلد totalRowCount فقط در بدنه پاسخ صفحه اول قرار می‌گیرد.
  • nextPageToken : توکنی که در درخواست‌های بعدی برای بازیابی صفحه بعدی ردیف‌ها ارسال می‌شود. اگر ردیف دیگری وجود نداشته باشد، API مربوط به آژانس‌ها و برندها این فیلد را از بدنه پاسخ حذف می‌کند.

در مثال agencies.reports.results.fetchRows REST، هر آیتم در فیلد rows مستقیماً به ReportDefinition پیکربندی شده در گزارش نگاشت می‌شود:

  • dimensionValues ​​: شامل مقادیر مربوط به هر بُعد در فیلد reportDefinition.dimensions به ترتیب دقیقی که شما مشخص کرده‌اید، می‌باشد. در مثال، مقدار اول، 2026-08-01 ، مربوط به بُعد DATE ، مقدار دوم، deal-1001 ، مربوط به بُعد DEAL_ID و مقدار سوم، creative-1001 ، مربوط به بُعد CREATIVE_ID است.

  • metricValueGroups : شامل مقادیر معیار گروه‌بندی‌شده در محدوده‌های تاریخ گزارش است. در هر گروه، فیلد primaryValues ​​شامل مقادیر مربوط به هر معیار در فیلد reportDefinition.metrics به ترتیب دقیقی است که شما مشخص کرده‌اید. در این مثال، هفت مقدار مربوط به مقادیر شمارشی Metric زیر هستند:

    • BIDS : 500000
    • BIDS_IN_AUCTION : 450000
    • AUCTIONS_WON : 150000
    • IMPRESSIONS : 150000
    • CLICKS : 3200
    • SPEND : 450.75
    • SPEND_WITHOUT_CURATION_PARTNER_FEE : 405.67

  • dateRanges : شامل محدوده تاریخ ثابتی است که گوگل برای محدوده نسبی THIS_MONTH_TO_DATE که در تعریف گزارش پیکربندی شده است، محاسبه کرده است.

مراحل بعدی