نسخه ۴ رابط برنامه‌نویسی کاربردی Campaign Manager 360 منسوخ شده و در تاریخ ۲۶ فوریه ۲۰۲۶ غیرفعال خواهد شد. برای جلوگیری از وقفه در سرویس، تا این تاریخ به نسخه ۵ مهاجرت کنید .

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

ایجاد و به روز رسانی گزارش ها

سرویس گزارش‌ها برای رابط برنامه‌نویسی کاربردی (API) مدیر کمپین ۳۶۰ به شما امکان می‌دهد گزارش‌های سازنده گزارش را با استفاده از اشیاء منبع گزارش ایجاد و به‌روزرسانی کنید. یک منبع گزارش، اطلاعات اولیه در مورد گزارشی که قرار است اجرا شود و همچنین ساختار خروجی گزارش را مشخص می‌کند.

این راهنما جزئیات نحوه ایجاد و به‌روزرسانی گزارش‌های Report Builder از طریق سرویس Reports را به صورت برنامه‌نویسی‌شده شرح می‌دهد.

پیکربندی منبع گزارش

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

ترجیحی : انجام یک به‌روزرسانی جزئی . با استفاده از این رویکرد، با یک منبع خالی شروع می‌کنید و فیلدهایی را که می‌خواهید تغییر دهید تنظیم می‌کنید. به‌روزرسانی جزئی فقط تغییرات فیلدهایی را که مشخص می‌کنید ذخیره می‌کند.
انجام یک به‌روزرسانی کامل. با استفاده از این رویکرد، یک منبع گزارش موجود را بارگذاری کرده و مستقیماً فیلدهای آن را تغییر می‌دهید. یک به‌روزرسانی کامل همیشه تمام فیلدهای گزارش را ذخیره می‌کند.

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

میدان	توضیحات
فیلدهای مورد نیاز
نام	نام گزارش.
نوع	نوع گزارش.
فیلدهای اختیاری
تحویل	تنظیمات ارسال ایمیل گزارش.
نام فایل	نام فایلی که هنگام تولید فایل‌های گزارش برای این گزارش استفاده شده است.
قالب	فرمت خروجی گزارش، CSV یا Excel.
برنامه	برنامه‌ای که برای اجرای گزارش شما به صورت مکرر استفاده می‌شود.

این فیلدهای مشترک، اسکلت گزارش شما را تشکیل می‌دهند. مثال زیر ایجاد یک منبع گزارش استاندارد جدید را نشان می‌دهد:

سی شارپ

Report report = new Report();

// Set the required fields "name" and "type".
report.Name = "Example standard report";
report.Type = "STANDARD";

// Set optional fields.
report.FileName = "example_report";
report.Format = "CSV";

جاوا

Report report = new Report();

// Set the required fields "name" and "type".
report.setName("Example standard report");
report.setType("STANDARD");

// Set optional fields
report.setFileName("example_report");
report.setFormat("CSV");

پی اچ پی

$report = new Google_Service_Dfareporting_Report();

// Set the required fields "name" and "type".
$report->setName('Example standard report');
$report->setType('STANDARD');

// Set optional fields.
$report->setFileName('example_report');
$report->setFormat('CSV');

پایتون

report = {
    # Set the required fields "name" and "type".
    'name': 'Example Standard Report',
    'type': 'STANDARD',
    # Set optional fields.
    'fileName': 'example_report',
    'format': 'CSV'
}

روبی

report = DfareportingUtils::API_NAMESPACE::Report.new(
  # Set the required fields "name" and "type".
  name: 'Example Standard Report',
  type: 'STANDARD',
  # Set optional fields.
  file_name: 'example_report',
  format: 'CSV'
)

معیارهای گزارش را تعریف کنید

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

معیارهای مورد استفاده به نوع گزارش بستگی دارد. رابطه بین نوع گزارش و معیارها در جدول زیر توضیح داده شده است:

نوع گزارش	فیلد معیارها
استاندارد	معیارها
رسیدن	معیارهای دسترسی
تبدیل مسیر	معیارهای تبدیل مسیر
نورافکن	معیارهای نورافکن
رسیدن به ابعاد متقاطع	معیارهای دسترسی متقاطع

اگرچه هر یک از این معیارهای خاص، مجموعه فیلدهای کمی متفاوتی را ارائه می‌دهند، مجموعه‌ای از فیلدهای معیار مشترک وجود دارد که عموماً برای کنترل خروجی گزارش مفید هستند:

میدان	توضیحات
محدوده تاریخ	تاریخ‌هایی که این گزارش باید برای آنها اجرا شود. می‌تواند برای تعیین تاریخ شروع و پایان سفارشی یا محدوده تاریخ نسبی استفاده شود. توجه: هنگام اجرای گزارش‌ها از طریق API، محدوده‌های تاریخ نسبی مانند `YESTERDAY` در منطقه زمانی آمریکا/لس‌آنجلس در نظر گرفته می‌شوند. این ممکن است نتایج غیرمنتظره‌ای را برای کاربران در مناطق زمانی مختلف ایجاد کند.
فیلترهای ابعادی	فهرستی از فیلترهایی که نتایج برگشتی را محدود می‌کنند. برای اطلاعات بیشتر در مورد پیکربندی فیلترها، به بخش مقادیر فیلتر پرس و جو مراجعه کنید.
ابعاد	فهرستی از عناصر Campaign Manager 360 که باید در خروجی گزارش لحاظ شوند.
نام‌های متریک	واحدهای اندازه‌گیری استاندارد برای گنجاندن در خروجی گزارش.

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

مثال زیر یک معیار اساسی به منبع گزارش استاندارد ما اضافه می‌کند:

سی شارپ

// Define a date range to report on. This example uses explicit start and
// end dates to mimic the "LAST_30_DAYS" relative date range.
DateRange dateRange = new DateRange();
dateRange.EndDate = DateTime.Now.ToString("yyyy-MM-dd");
dateRange.StartDate = DateTime.Now.AddDays(-30).ToString("yyyy-MM-dd");

// Create a report criteria.
SortedDimension dimension = new SortedDimension();
dimension.Name = "advertiser";

Report.CriteriaData criteria = new Report.CriteriaData();
criteria.DateRange = dateRange;
criteria.Dimensions = new List<SortedDimension>() { dimension };
criteria.MetricNames = new List<string>() {
  "clicks",
  "impressions"
};

// Add the criteria to the report resource.
report.Criteria = criteria;

جاوا

// Define a date range to report on. This example uses explicit start and end dates to mimic
// the "LAST_MONTH" relative date range.
DateRange dateRange = new DateRange();
dateRange.setEndDate(new DateTime(true, System.currentTimeMillis(), null));

Calendar lastMonth = Calendar.getInstance();
lastMonth.add(Calendar.MONTH, -1);
dateRange.setStartDate(new DateTime(true, lastMonth.getTimeInMillis(), null));

// Create a report criteria.
Report.Criteria criteria = new Report.Criteria();
criteria.setDateRange(dateRange);
criteria.setDimensions(Lists.newArrayList(new SortedDimension().setName("advertiser")));
criteria.setMetricNames(Lists.newArrayList("clicks", "impressions"));

// Add the criteria to the report resource.
report.setCriteria(criteria);

پی اچ پی

// Define a date range to report on. This example uses explicit start and
// end dates to mimic the "LAST_30_DAYS" relative date range.
$dateRange = new Google_Service_Dfareporting_DateRange();
$dateRange->setStartDate(
    date('Y-m-d', mktime(0, 0, 0, date('m'), date('d') - 30, date('Y')))
);
$dateRange->setEndDate(date('Y-m-d'));

// Create a report criteria.
$dimension = new Google_Service_Dfareporting_SortedDimension();
$dimension->setName('advertiser');

$criteria = new Google_Service_Dfareporting_ReportCriteria();
$criteria->setDateRange($dateRange);
$criteria->setDimensions([$dimension]);
$criteria->setMetricNames(['clicks', 'impressions']);

// Add the criteria to the report resource.
$report->setCriteria($criteria);

پایتون

# Define a date range to report on. This example uses explicit start and end
# dates to mimic the "LAST_30_DAYS" relative date range.
end_date = date.today()
start_date = end_date - timedelta(days=30)

# Create a report criteria.
criteria = {
    'dateRange': {
        'startDate': start_date.strftime('%Y-%m-%d'),
        'endDate': end_date.strftime('%Y-%m-%d')
    },
    'dimensions': [{
        'name': 'advertiser'
    }],
    'metricNames': ['clicks', 'impressions']
}

# Add the criteria to the report resource.
report['criteria'] = criteria

روبی

# Define a date range to report on. This example uses explicit start and end
# dates to mimic the "LAST_30_DAYS" relative date range.
start_date = DateTime.now.prev_day(30).strftime('%Y-%m-%d')
end_date = DateTime.now.strftime('%Y-%m-%d')

# Create a report criteria
criteria = DfareportingUtils::API_NAMESPACE::Report::Criteria.new(
  date_range: DfareportingUtils::API_NAMESPACE::DateRange.new(
    start_date: start_date,
    end_date: end_date
  ),
  dimensions: [
    DfareportingUtils::API_NAMESPACE::SortedDimension.new(
      name: 'advertiser'
    )
  ],
  metric_names: ['clicks', 'impressions']
)

# Add the criteria to the report resource.
report.criteria = criteria

مقادیر فیلتر پرس و جو

هنگام پیکربندی فیلترها برای یک گزارش، باید مقادیر دقیقی را که فیلترها برای محدود کردن خروجی گزارش استفاده می‌کنند، مشخص کنید. اگر مطمئن نیستید که مقادیر ممکن برای یک فیلتر خاص چیست، آنها را با استفاده از سرویس DimensionValues جستجو کنید.

یک پرس‌وجوی مقادیر بُعد پایه شامل یک نام بُعد و همچنین یک تاریخ شروع و یک تاریخ پایان است . تاریخ‌های شروع و پایان، پاسخ را به مقادیر معتبر در آن بازه زمانی محدود می‌کنند. در صورت نیاز به محدود کردن بیشتر نتایج پرس‌وجو، می‌توان فیلترهای اضافی تعیین کرد.

مثال زیر مقادیر معتبر فیلتر تبلیغ‌کننده را در طول تاریخ‌هایی که گزارش ما اجرا خواهد شد، جستجو می‌کند و آنها را به معیارهای گزارش اضافه می‌کند:

سی شارپ

// Query advertiser dimension values for report run dates.
DimensionValueRequest request = new DimensionValueRequest();
request.StartDate = report.Criteria.DateRange.StartDate;
request.EndDate = report.Criteria.DateRange.EndDate;
request.DimensionName = "advertiser";

DimensionValueList values =
    service.DimensionValues.Query(request, profileId).Execute();

if (values.Items.Any()) {
  // Add a value as a filter to the report criteria.
  report.Criteria.DimensionFilters = new List<DimensionValue>() {
    values.Items[0]
  };
}

جاوا

// Query advertiser dimension values for report run dates.
DimensionValueRequest request = new DimensionValueRequest();
request.setStartDate(report.getCriteria().getDateRange().getStartDate());
request.setEndDate(report.getCriteria().getDateRange().getEndDate());
request.setDimensionName("advertiser");

DimensionValueList values = reporting.dimensionValues().query(profileId, request).execute();

if (!values.getItems().isEmpty()) {
  // Add a value as a filter to the report criteria.
  List<DimensionValue> filters = Lists.newArrayList(values.getItems().get(0));
  report.getCriteria().setDimensionFilters(filters);
}

پی اچ پی

// Query advertiser dimension values for report run dates.
$request = new Google_Service_Dfareporting_DimensionValueRequest();
$request->setStartDate(
    $report->getCriteria()->getDateRange()->getStartDate()
);
$request->setEndDate(
    $report->getCriteria()->getDateRange()->getEndDate()
);
$request->setDimensionName('advertiser');

$values =
    $this->service->dimensionValues->query($userProfileId, $request);

if (!empty($values->getItems())) {
    // Add a value as a filter to the report criteria.
    $report->getCriteria()->setDimensionFilters([$values->getItems()[0]]);
}

پایتون

# Query advertiser dimension values for report run dates.
request = {
    'dimensionName': 'advertiser',
    'endDate': report['criteria']['dateRange']['endDate'],
    'startDate': report['criteria']['dateRange']['startDate']
}

values = service.dimensionValues().query(
    profileId=profile_id, body=request).execute()

if values['items']:
  # Add a value as a filter to the report criteria.
  report['criteria']['dimensionFilters'] = [values['items'][0]]

روبی

# Query advertiser dimension values for report run dates.
dimension = DfareportingUtils::API_NAMESPACE::DimensionValueRequest.new(
  dimension_name: 'advertiser',
  start_date: report.criteria.date_range.start_date,
  end_date: report.criteria.date_range.end_date
)

values = service.query_dimension_value(profile_id, dimension)

unless values.items.empty?
  # Add a value as a filter to the report criteria.
  report.criteria.dimension_filters = [values.items.first]
end

تعیین سازگاری فیلد

هنگام پیکربندی معیارهای گزارش، مهم است به یاد داشته باشید که همه ترکیبات معیارها، ابعاد و فیلترها معتبر نیستند. شما مجاز به ذخیره گزارشی که حاوی ترکیبی نامعتبر باشد، نخواهید بود، بنابراین مهم است که مطمئن شوید فیلدهایی که قصد استفاده از آنها را دارید با یکدیگر سازگار هستند.

همزمان با ساخت منبع گزارش خود، می‌توانید آن را به سرویس Reports.compatibleFields ارسال کنید تا ببینید کدام فیلدها با توجه به فیلدهایی که قبلاً انتخاب کرده‌اید، معتبر هستند. پیکربندی گزارش تجزیه و تحلیل می‌شود و پاسخی حاوی ابعاد، معیارها و فیلترهای سازگار بازگردانده می‌شود. از آنجایی که تضمینی وجود ندارد که فیلدهای موجود در این پاسخ با یکدیگر سازگار باشند، ممکن است لازم باشد چندین درخواست ارسال کنید تا مطمئن شوید که همه فیلدهایی که انتخاب می‌کنید با هم کار می‌کنند.

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

سی شارپ

CompatibleFields fields =
    service.Reports.CompatibleFields.Query(report, profileId).Execute();

ReportCompatibleFields reportFields = fields.ReportCompatibleFields;

if(reportFields.Dimensions.Any()) {
  // Add a compatible dimension to the report.
  Dimension dimension = reportFields.Dimensions[0];
  SortedDimension sortedDimension = new SortedDimension();
  sortedDimension.Name = dimension.Name;
  report.Criteria.Dimensions.Add(sortedDimension);
} else if (reportFields.Metrics.Any()) {
  // Add a compatible metric to the report.
  Metric metric = reportFields.Metrics[0];
  report.Criteria.MetricNames.Add(metric.Name);
}

جاوا

CompatibleFields fields = reporting.reports().compatibleFields()
    .query(profileId, report).execute();

ReportCompatibleFields reportFields = fields.getReportCompatibleFields();

if (!reportFields.getDimensions().isEmpty()) {
  // Add a compatible dimension to the report.
  Dimension dimension = reportFields.getDimensions().get(0);
  SortedDimension sortedDimension = new SortedDimension().setName(dimension.getName());
  report.getCriteria().getDimensions().add(sortedDimension);
} else if (!reportFields.getMetrics().isEmpty()) {
  // Add a compatible metric to the report.
  Metric metric = reportFields.getMetrics().get(0);
  report.getCriteria().getMetricNames().add(metric.getName());
}

پی اچ پی

$fields = $this->service->reports_compatibleFields->query(
    $userProfileId,
    $report
);

$reportFields = $fields->getReportCompatibleFields();

if (!empty($reportFields->getDimensions())) {
    // Add a compatible dimension to the report.
    $dimension = $reportFields->getDimensions()[0];
    $sortedDimension = new Google_Service_Dfareporting_SortedDimension();
    $sortedDimension->setName($dimension->getName());
    $report->getCriteria()->setDimensions(
        array_merge(
            $report->getCriteria()->getDimensions(),
            [$sortedDimension]
        )
    );
} elseif (!empty($reportFields->getMetrics())) {
    // Add a compatible metric to the report.
    $metric = $reportFields->getMetrics()[0];
    $report->getCriteria()->setMetricNames(
        array_merge(
            $report->getCriteria()->getMetricNames(),
            [$metric->getName()]
        )
    );
}

پایتون

fields = service.reports().compatibleFields().query(
    profileId=profile_id, body=report).execute()

report_fields = fields['reportCompatibleFields']

if report_fields['dimensions']:
  # Add a compatible dimension to the report.
  report['criteria']['dimensions'].append({
      'name': report_fields['dimensions'][0]['name']
  })
elif report_fields['metrics']:
  # Add a compatible metric to the report.
  report['criteria']['metricNames'].append(
      report_fields['metrics'][0]['name'])

روبی

fields = service.query_report_compatible_field(profile_id, report)

report_fields = fields.report_compatible_fields

if report_fields.dimensions.any?
  # Add a compatible dimension to the report.
  report.criteria.dimensions <<
    DfareportingUtils::API_NAMESPACE::SortedDimension.new(
      name: report_fields.dimensions.first.name
    )
elsif report_fields.metrics.any?
  # Add a compatible metric to the report.
  report.criteria.metric_names << report_fields.metrics.first.name
end

گزارش را ذخیره کنید

مرحله آخر در این فرآیند، ذخیره منبع گزارش شما است. اگر در حال ایجاد یک گزارش جدید هستید، می‌توانید آن را با فراخوانی Reports.insert وارد کنید:

سی شارپ

Report insertedReport =
    service.Reports.Insert(report, profileId).Execute();

جاوا

Report insertedReport = reporting.reports().insert(profileId, report).execute();

پی اچ پی

$insertedReport =
    $this->service->reports->insert($userProfileId, $report);

پایتون

inserted_report = service.reports().insert(
    profileId=profile_id, body=report).execute()

روبی

report = service.insert_report(profile_id, report)

اگر در حال انجام یک به‌روزرسانی جزئی هستید، می‌توانید با فراخوانی Reports.patch تغییرات خود را ذخیره کنید:

سی شارپ

// Patch an existing report.
Report patchedReport =
    service.Reports.Patch(report, profileId, reportId).Execute();

جاوا

// Patch an existing report.
Report patchedReport = reporting.reports().patch(profileId, reportId, report).execute();

پی اچ پی

# Patch an existing report.
$patchedReport =
    $this->service->reports->patch($userProfileId, $reportId, $report)

پایتون

# Patch an existing report.
patched_report = service.reports().patch(
    profileId=profile_id, reportId=report_id, body=report).execute();

روبی

# Patch an existing report.
patched_report = service.patch_report(profile_id, report_id, report)

یا اگر تصمیم به انجام یک به‌روزرسانی کامل دارید، می‌توانید با فراخوانی Reports.update تغییرات خود را ذخیره کنید:

سی شارپ

// Update an existing report.
Report updatedReport =
    service.Reports.Update(report, profileId, report.Id).Execute();

جاوا

// Update an existing report.
Report updatedReport = reporting.reports().update(profileId, report.getId(), report).execute();

پی اچ پی

# Update an existing report.
$updatedReport =
    $this->service->reports->update($userProfileId, $report->getId(), $report)

پایتون

# Update an existing report.
updated_report = service.reports().update(
    profileId=profile_id, reportId=report['id'], body=report).execute();

روبی

# Update an existing report.
updated_report = service.update_report(profile_id, report.id, report);

پس از یک درخواست ذخیره موفقیت‌آمیز، یک کپی از منبع گزارش در بدنه پاسخ بازگردانده می‌شود. این منبع چند فیلد جدید پر شده خواهد داشت که مهمترین آنها فیلد id است. این id همان چیزی است که شما برای ارجاع به این گزارش در ادامه گردش کار خود استفاده خواهید کرد.

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

پیکربندی منبع گزارش

سی شارپ

جاوا

پی اچ پی

پایتون

روبی

معیارهای گزارش را تعریف کنید

سی شارپ

جاوا

پی اچ پی

پایتون

روبی

مقادیر فیلتر پرس و جو

سی شارپ

جاوا

پی اچ پی

پایتون

روبی

تعیین سازگاری فیلد

سی شارپ

جاوا

پی اچ پی

پایتون

روبی

گزارش را ذخیره کنید

سی شارپ

جاوا

پی اچ پی

پایتون

روبی

سی شارپ

جاوا

پی اچ پی

پایتون

روبی

سی شارپ

جاوا

پی اچ پی

پایتون

روبی

ایجاد و به روز رسانی گزارش ها