این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

ایجاد و اصلاح گزارش‌ها

شیء Report ) یک الگوی قابل استفاده مجدد را تعریف می‌کند که گزارشی را که می‌خواهید تولید کنید، توصیف می‌کند. شیء Report معیارهایی مانند ابعاد، معیارها و محدوده تاریخ گزارش را پیکربندی می‌کند.

این راهنما توضیح می‌دهد که چگونه می‌توانید از API Curation Partners برای ایجاد گزارشی جهت ردیابی عملکرد، اصلاح گزارش موجود برای تطابق بهتر با نیازهایتان یا حذف الگویی برای یک گزارش منسوخ استفاده کنید.

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

قبل از ادامه، باید احراز هویت را تنظیم کنید .

ایجاد گزارش

شما می‌توانید با استفاده از متد curators.reports.create یک گزارش ایجاد کنید. یک گزارش، ابعاد، معیارها، محدوده تاریخ، منطقه زمانی، فیلترها و مرتب‌سازی‌های پیش‌فرض را برای کوئری‌های گزارش‌گیری شما پیکربندی می‌کند.

مثال زیر یک درخواست POST به متد curators.reports.create با بدنه JSON حاوی یک شیء Report ارسال می‌کند:

استراحت

درخواست

curl --request POST \
  'https://curationpartners.googleapis.com/v1/curators/ACCOUNT_ID/reports' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "displayName": "Monthly Data Segment Performance",
    "reportDefinition": {
      "dimensions": [
        "DATE",
        "CURATION_DATA_SEGMENT_ID"
      ],
      "metrics": [
        "IMPRESSIONS",
        "CLICKS",
        "SPEND",
        "CURATION_PARTNER_FEE"
      ],
      "dateRange": {
        "relative": "LAST_30_DAYS"
      },
      "timeZoneSource": "UTC"
    }
  }' \
  --compressed

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

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

پاسخ

{
  "name": "curators/ACCOUNT_ID/reports/123456789",
  "reportId": "123456789",
  "displayName": "Monthly Data Segment Performance",
  "reportDefinition": {
    "dimensions": [
      "DATE",
      "CURATION_DATA_SEGMENT_ID"
    ],
    "metrics": [
      "IMPRESSIONS",
      "CLICKS",
      "SPEND",
      "CURATION_PARTNER_FEE"
    ],
    "dateRange": {
      "relative": "LAST_30_DAYS"
    },
    "timeZoneSource": "UTC"
  },
  "createTime": "2026-08-01T10:00:00Z",
  "updateTime": "2026-08-01T10:00:00Z",
  "locale": "en"
}

هنگام ایجاد یک گزارش، باید شیء reportDefinition را با فیلدهای زیر پر کنید:

dimensions : فهرست ابعادی که می‌توانید برای گروه‌بندی معیارها در گزارش خود استفاده کنید، مانند DATE ، CURATION_DATA_SEGMENT_ID ، DEAL_ID یا ENVIRONMENT .
metrics : فهرست معیارهایی که باید تجمیع شوند، مانند IMPRESSIONS ، CLICKS ، SPEND ) یا CURATION_PARTNER_FEE .
dateRange : محدوده تاریخ برای گزارش. محدوده تاریخ یا به صورت یک محدوده نسبت به زمان اجرای گزارش مانند LAST_30_DAYS یا YESTERDAY یا یک محدوده ثابت با startDate و endDate مشخص می‌شود.

شما می‌توانید فیلدهای زیر را به صورت اختیاری پیکربندی کنید:

timeZoneSource : منبع منطقه زمانی اعمال شده به گزارش. به طور پیش‌فرض روی مقدار شمارشی AD_EXCHANGE تنظیم شده است که از منطقه زمانی اقیانوس آرام استفاده می‌کند.
timeZone : یک رشته منطقه زمانی IANA - برای مثال، "America/New_York" . هنگام تنظیم فیلد timeZoneSource با مقدار PROVIDED ، باید این فیلد را نیز پر کنید.
filters : داده‌های گزارش را به ابعاد یا مقادیر متریک خاصی که شما مشخص می‌کنید، محدود می‌کند.
sorts : ترتیب مرتب‌سازی پیش‌فرض برای ردیف‌های نتایج گزارش.

جاوا

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

import com.google.api.services.curationpartners.v1.CurationPartners;
import com.google.api.services.curationpartners.v1.model.DateRange;
import com.google.api.services.curationpartners.v1.model.Report;
import com.google.api.services.curationpartners.v1.model.ReportDefinition;
import com.google.api.services.samples.curationpartners.v1.Utils;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.List;
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 CreateReport {

  /**
   * Executes the create operation for a report.
   *
   * @param curationPartnersClient the initialized Curation Partners API client.
   * @param accountId the account ID of the curator that will create the report.
   * @param displayName the display name of the report to be created.
   * @param dimensions the list of dimensions to include in the report definition.
   * @param metrics the list of metrics to include in the report definition.
   * @param relativeDateRange the relative date range for the report.
   * @throws IOException if the API returns an error.
   */
  public static void execute(
      CurationPartners curationPartnersClient,
      Long accountId,
      String displayName,
      List<String> dimensions,
      List<String> metrics,
      String relativeDateRange)
      throws IOException {
    String parent = String.format("curators/%s", accountId);

    System.out.printf("Creating Report \"%s\" for curator with name \"%s\".%n",
        displayName, parent);

    ReportDefinition reportDefinition =
        new ReportDefinition()
            .setDimensions(dimensions)
            .setMetrics(metrics)
            .setDateRange(new DateRange().setRelative(relativeDateRange));

    Report newReport =
        new Report()
            .setDisplayName(displayName)
            .setReportDefinition(reportDefinition);

    // Create a new report.
    Report createdReport =
        curationPartnersClient
            .curators()
            .reports()
            .create(parent, newReport)
            .execute();

    System.out.println("Successfully created report:");
    Utils.jsonPrettyPrint(createdReport);
  }

  /**
   * Creates and configures the ArgumentParser for this sample.
   *
   * @return the configured ArgumentParser.
   */
  private static ArgumentParser createArgumentParser() {
    ArgumentParser parser =
        ArgumentParsers.newFor("CreateReport")
            .build()
            .defaultHelp(true)
            .description("Creates a new report for the given curator account.");

    // Required arguments.
    parser
        .addArgument("-a", "--account_id")
        .help("The account ID of the curator that will create the report.")
        .required(true)
        .type(Long.class);
    parser
        .addArgument("-d", "--display_name")
        .help("The display name of the report to be created.")
        .required(true);
    parser
        .addArgument("--dimensions")
        .help("The space-delimited list of dimensions to include in the report definition " +
            "(for example: DATE BUYER_NAME). For a listing of possible values, see: " +
            "https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#dimension")
        .required(true)
        .nargs("+");
    parser
        .addArgument("--metrics")
        .help("The space-delimited list of metrics to include in the report definition " +
            "(for example: IMPRESSIONS CLICKS). For a listing of possible values, see: " +
            "https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#metric")
        .required(true)
        .nargs("+");

    // Optional arguments.
    parser
        .addArgument("--relative_date_range")
        .help("The relative date range for the report to include in the report definition. (for example: LAST_7_DAYS, TODAY, YESTERDAY). " +
            "Defaults to LAST_7_DAYS if unspecified. For a listing of possible values, see: " +
            "https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#relativedaterange")
        .setDefault("LAST_7_DAYS");

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

    Long accountId = parsedArgs.getLong("account_id");
    String displayName = parsedArgs.getString("display_name");
    List<String> dimensions = parsedArgs.getList("dimensions");
    List<String> metrics = parsedArgs.getList("metrics");
    String relativeDateRange = parsedArgs.getString("relative_date_range");

    try {
      execute(client, accountId, displayName, dimensions, metrics, relativeDateRange);
    } catch (IOException ex) {
      System.out.printf("Curation Partners API returned error response:%n%s", ex);
      System.exit(1);
    }
  }
}

اصلاح گزارش موجود

برای تغییر یک گزارش موجود، از متد curators.reports.patch استفاده کنید. برای مشخص کردن اینکه کدام فیلدها باید به‌روزرسانی شوند، از پارامتر کوئری updateMask استفاده کنید.

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

استراحت

درخواست

curl --request PATCH \
  'https://curationpartners.googleapis.com/v1/curators/ACCOUNT_ID/reports/123456789?updateMask=displayName,reportDefinition.dateRange.relative' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "displayName": "Updated Data Segment Performance",
    "reportDefinition": {
      "dateRange": {
        "relative": "THIS_MONTH_TO_DATE"
      }
    }
  }' \
  --compressed

پاسخ

{
  "name": "curators/ACCOUNT_ID/reports/123456789",
  "reportId": "123456789",
  "displayName": "Updated Data Segment Performance",
  "reportDefinition": {
    "dimensions": [
      "DATE",
      "CURATION_DATA_SEGMENT_ID"
    ],
    "metrics": [
      "IMPRESSIONS",
      "CLICKS",
      "SPEND",
      "CURATION_PARTNER_FEE"
    ],
    "dateRange": {
      "relative": "THIS_MONTH_TO_DATE"
    },
    "timeZoneSource": "UTC"
  },
  "createTime": "2026-08-01T10:00:00Z",
  "updateTime": "2026-08-01T10:10:00Z",
  "locale": "en"
}

جاوا

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

import com.google.api.services.curationpartners.v1.CurationPartners;
import com.google.api.services.curationpartners.v1.model.DateRange;
import com.google.api.services.curationpartners.v1.model.Report;
import com.google.api.services.curationpartners.v1.model.ReportDefinition;
import com.google.api.services.samples.curationpartners.v1.Utils;

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.ArrayList;
import java.util.List;
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 PatchReport {

  private PatchReport() {}

  /**
   * Executes the patch operation for a report.
   *
   * @param curationPartnersClient the initialized Curation Partners API client.
   * @param accountId the account ID of the curator that created the report.
   * @param reportId the resource ID of the report to update.
   * @param displayName the modified display name for the report (or null if not being modified).
   * @param relativeDateRange the modified relative date range for the report definition (or null
   *     if not being modified).
   * @param dimensions the modified list of dimensions for the report definition (or null if not
   *     being modified).
   * @param metrics the modified list of metrics for the report definition (or null if not being
   *     modified).
   * @throws IOException if the API returns an error.
   */
  public static void execute(
      CurationPartners curationPartnersClient,
      Long accountId,
      String reportId,
      String displayName,
      String relativeDateRange,
      List<String> dimensions,
      List<String> metrics)
      throws IOException {

    String name = String.format("curators/%d/reports/%s", accountId, reportId);

    List<String> patchedFields = new ArrayList<>();
    Report patchedReport = new Report();

    if (displayName != null) {
      patchedReport.setDisplayName(displayName);
      patchedFields.add("displayName");
    }

    ReportDefinition reportDefinition = new ReportDefinition();
    if (relativeDateRange != null) {
      reportDefinition.setDateRange(new DateRange().setRelative(relativeDateRange));
      patchedFields.add("reportDefinition.dateRange.relative");
    }
    if (dimensions != null) {
      reportDefinition.setDimensions(dimensions);
      patchedFields.add("reportDefinition.dimensions");
    }
    if (metrics != null) {
      reportDefinition.setMetrics(metrics);
      patchedFields.add("reportDefinition.metrics");
    }
    // Set the ReportDefinition on the patched Report unconditionally. Any fields not
    // explicitly specified in the updateMask will be ignored by the API.
    patchedReport.setReportDefinition(reportDefinition);

    if (patchedFields.isEmpty()) {
      System.out.println("No fields specified to update.");
      return;
    }

    String updateMask = String.join(",", patchedFields);

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

    // Patch the report.
    Report returnedReport =
        curationPartnersClient
            .curators()
            .reports()
            .patch(name, patchedReport)
            .setUpdateMask(updateMask)
            .execute();

    System.out.println("Successfully patched report:");
    Utils.jsonPrettyPrint(returnedReport);
  }

  /**
   * Creates and configures the ArgumentParser for this sample.
   *
   * @return the configured ArgumentParser.
   */
  private static ArgumentParser createArgumentParser() {
    ArgumentParser parser =
        ArgumentParsers.newFor("PatchReport")
            .build()
            .defaultHelp(true)
            .description("Updates a specified report.");

    // Required arguments.
    parser
        .addArgument("-a", "--account_id")
        .help("The account ID of the curator that created the report.")
        .required(true)
        .type(Long.class);
    parser
        .addArgument("-r", "--report_id")
        .help("The resource ID of the report to update.")
        .required(true);

    // Optional arguments.
    parser
        .addArgument("-d", "--display_name")
        .help("The modified display name of the report.");
    parser
        .addArgument("--relative_date_range")
        .help("The modified relative date range for the report definition (for example: " +
            "LAST_7_DAYS, TODAY, YESTERDAY). For a listing of possible values, see: " +
            "https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#relativedaterange");
    parser
        .addArgument("--dimensions")
        .help("A space-delimited list of modified dimensions for the report definition (for " +
            "example: DATE, BUYER_NAME). For a listing of possible values, see: " +
            "https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#dimension")
        .nargs("+");
    parser
        .addArgument("--metrics")
        .help("A space-delimited list of modified metrics for the report definition (for " +
            "example: IMPRESSIONS CLICKS). For a listing of possible values, see: " +
            "https://developers.google.com/authorized-buyers/curation/apis/curationpartners/reference/rest/v1/curators.reports#metric")
        .nargs("+");

    return parser;
  }

  public static void main(String[] args) {
    ArgumentParser parser = createArgumentParser();
    Namespace parsedArgs = null;
    try {
      parsedArgs = parser.parseArgs(args);
    } catch (ArgumentParserException e) {
      parser.handleError(e);
      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);
    }

    Long accountId = parsedArgs.getLong("account_id");
    String reportId = parsedArgs.getString("report_id");
    String displayName = parsedArgs.getString("display_name");
    String relativeDateRange = parsedArgs.getString("relative_date_range");
    List<String> dimensions = parsedArgs.getList("dimensions");
    List<String> metrics = parsedArgs.getList("metrics");

    try {
      execute(
          client, accountId, reportId, displayName, relativeDateRange, dimensions, metrics);
    } catch (IOException e) {
      System.out.printf("Curation Partners API returned error response:%n%s", e);
      System.exit(1);
    }
  }
}

حذف یک گزارش

برای حذف گزارشی که دیگر نیازی به آن ندارید، از متد curators.reports.delete استفاده کنید. پس از حذف یک گزارش، دیگر نمی‌توانید از آن گزارش برای اجرای گزارش‌های بعدی استفاده کنید. همچنین نمی‌توانید گزارش را با متدهای curators.reports.get یا curators.reports.list بازیابی کنید.

مثال زیر یک درخواست DELETE برای حذف گزارش مشخص شده ارسال می‌کند:

استراحت

درخواست

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

پاسخ

{}

جاوا

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

import com.google.api.services.curationpartners.v1.CurationPartners;
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 DeleteReport {

  /**
   * Executes the delete operation for a report.
   *
   * @param curationPartnersClient the initialized Curation Partners API client.
   * @param accountId the account ID of the curator that created the report.
   * @param reportId the resource ID of the report to delete.
   * @throws IOException if the API returns an error.
   */
  public static void execute(
      CurationPartners curationPartnersClient, Long accountId, String reportId)
      throws IOException {
    String name = String.format("curators/%s/reports/%s", accountId, reportId);

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

    // Delete the specified report.
    curationPartnersClient.curators().reports().delete(name).execute();

    System.out.println("Successfully deleted report.");
  }

  /**
   * Creates and configures the ArgumentParser for this sample.
   *
   * @return the configured ArgumentParser.
   */
  private static ArgumentParser createArgumentParser() {
    ArgumentParser parser =
        ArgumentParsers.newFor("DeleteReport")
            .build()
            .defaultHelp(true)
            .description("Deletes a specified report.");

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

مراحل بعدی

یاد بگیرید که چگونه گزارش‌ها را با استفاده از رابط برنامه‌نویسی کاربردی Curation Partners مشاهده کنید .
یاد بگیرید که چگونه گزارش‌ها را با رابط برنامه‌نویسی کاربردی Curation Partners اجرا کنید .
یاد بگیرید که چگونه با استفاده از رابط برنامه‌نویسی کاربردی Curation Partners، نظرسنجی انجام دهید و گزارش‌های تکمیل‌شده را مشاهده کنید .

ایجاد و اصلاح گزارش‌ها با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

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

ایجاد گزارش

استراحت

درخواست

پاسخ

جاوا

اصلاح گزارش موجود

استراحت

درخواست

پاسخ

جاوا

حذف یک گزارش

استراحت

درخواست

پاسخ

جاوا

مراحل بعدی

ایجاد و اصلاح گزارش‌ها