گزارش ها را اجرا کنید

برای تولید داده‌های عملکرد برای حساب کاربری آژانس خود، گزارشی را اجرا کنید تا یک عملیات ناهمزمان برای یک الگوی Report موجود آغاز شود.

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

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

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

شروع اجرای گزارش

برای اجرای یک گزارش موجود، از متد agencies.reports.run استفاده کنید.

مثال زیر یک درخواست POST برای شروع اجرای گزارش ارسال می‌کند:

استراحت

درخواست 

curl --request POST \
  'https://agenciesandbrands.googleapis.com/v1/agencies/ACCOUNT_ID/reports/123456789:run' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --compressed

موارد زیر را جایگزین کنید:

  • ACCOUNT_ID : شناسه حساب شما.
  • ACCESS_TOKEN : توکن دسترسی شما.

پاسخ 

{
  "name": "agencies/ACCOUNT_ID/reports/123456789/operations/10486370264",
  "done": false,
  "metadata": {
    "@type": "type.googleapis.com/google.ads.agenciesandbrands.v1.RunReportMetadata"
  }
}

جاوا 

/*
 * 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;

import com.google.api.services.agenciesandbrands.v1.AgenciesAndBrands;
import com.google.api.services.agenciesandbrands.v1.model.Operation;
import com.google.api.services.agenciesandbrands.v1.model.RunReportRequest;
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 RunReport {

  /**
   * Executes the run operation for a report.
   *
   * @param agenciesAndBrandsClient the initialized Agencies & Brands API client.
   * @param accountId the account ID of the agency that created the report.
   * @param reportId the resource ID of the report to run.
   * @throws IOException if the API returns an error.
   */
  public static void execute(
      AgenciesAndBrands agenciesAndBrandsClient, Long accountId, String reportId)
      throws IOException {
    String name = String.format("agencies/%s/reports/%s", accountId, reportId);

    System.out.printf("Running report with name \"%s\".%n", name);

    RunReportRequest requestBody = new RunReportRequest();

    // Run the specified report to start an asynchronous operation.
    Operation operation =
        agenciesAndBrandsClient
            .agencies()
            .reports()
            .run(name, requestBody)
            .execute();

    System.out.println("Successfully initiated report run operation:");
    Utils.jsonPrettyPrint(operation);
  }

  /**
   * Creates and configures the ArgumentParser for this sample.
   *
   * @return the configured ArgumentParser.
   */
  private static ArgumentParser createArgumentParser() {
    ArgumentParser parser =
        ArgumentParsers.newFor("RunReport")
            .build()
            .defaultHelp(true)
            .description("Runs a specified report asynchronously, returning an Operation " +
                "that can be used to track its progress.");

    // Required arguments.
    parser
        .addArgument("-a", "--account_id")
        .help("The account ID of the agency that created the report.")
        .required(true)
        .type(Long.class);
    parser
        .addArgument("-r", "--report_id")
        .help("The resource ID of the report to run.")
        .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"));
    } catch (IOException ex) {
      System.out.printf("Agencies & Brands API returned error response:%n%s", ex);
      System.exit(1);
    }
  }
}

اجرای یک گزارش یک عملیات طولانی مدت ناهمزمان است. وقتی متد run را فراخوانی می‌کنید، API مربوط به Agencies & Brands با یک منبع Operation پاسخ می‌دهد. فیلد name در این عملیات، عملیات اجرا را مشخص می‌کند و فرمت آن به صورت زیر است:

agencies/ACCOUNT_ID/reports/REPORT_ID/operations/OPERATION_ID

شیء Operation برگردانده شده شامل موارد زیر است:

  • name : نامی که سرور برای عملیات طولانی مدت اختصاص داده است. REPORT_ID یک شناسه منحصر به فرد برای الگوی گزارشی است که اجرا کرده‌اید. OPERATION_ID یک شناسه منحصر به فرد است که گوگل هنگام اجرای الگوی گزارش به عملیاتی که ایجاد می‌کنید اختصاص می‌دهد.
  • metadata : اطلاعات پیشرفت اختیاری مختص سرویس. فیلد metadata ممکن است در شیء Operation که در پاسخ agencies.reports.run دریافت می‌کنید، پر نشده باشد.

پس از شروع اجرای گزارش، تا زمانی که فیلد done عملیات مقدار true را نداشته باشد، نمی‌توانید نتایج گزارش را مشاهده کنید. مدت زمانی که اجرای گزارش برای تکمیل شدن طول می‌کشد، بسته به پیچیدگی گزارش متفاوت است.

مراحل بعدی