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

سرویس Reports برای Campaign Manager 360 API به شما امکان می دهد گزارش های Report Builder را با استفاده از اشیاء منبع گزارش ایجاد و به روز کنید. یک منبع گزارش، اطلاعات اولیه در مورد گزارشی که باید اجرا شود، و همچنین ساختار خروجی گزارش را مشخص می کند.

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

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

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

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

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

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

میدان	توضیحات
فیلدهای مورد نیاز
نام	نام گزارش.
نوع	نوع گزارش
فیلدهای اختیاری
تحویل	تنظیمات تحویل ایمیل گزارش.
نام فایل	نام فایلی که هنگام ایجاد فایل های گزارش برای این گزارش استفاده می شود.
قالب	فرمت خروجی گزارش، 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");

PHP

$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'
)

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

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

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

نوع گزارش	زمینه معیار
استاندارد	معیارها
رسیدن	معیارهای رسیدن
PATH_TO_CONVERSION	pathToConversionCriteria
نور افکن	معیارهای نورافکن
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

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

میدان	توضیحات
محدوده تاریخ	تاریخ هایی که این گزارش باید برای آنها اجرا شود. می توان از آن برای تعیین تاریخ شروع و پایان سفارشی یا محدوده تاریخ نسبی استفاده کرد. توجه: هنگام اجرای گزارش‌ها از طریق 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);

PHP

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

PHP

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

PHP

$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();

PHP

$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();

PHP

# 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();

PHP

# 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 است. این شناسه همان چیزی است که برای ارجاع به این گزارش در بقیه گردش کار خود استفاده خواهید کرد.