إنشاء التقارير وتحديثها

تتيح لك خدمة التقارير في Campaign Manager 360 API إنشاء تقارير "أداة إنشاء التقارير" وتعديلها باستخدام عناصر موارد التقارير. يحدّد مورد التقرير المعلومات الأساسية حول التقرير الذي سيتم تنفيذه، بالإضافة إلى بنية ناتج التقرير.

يوضّح هذا الدليل بالتفصيل كيفية إنشاء تقارير "أداة إنشاء التقارير" وتعديلها آليًا من خلال خدمة "التقارير".

ملاحظة: إنّ إنشاء تقرير صالح ليس مهمة بسيطة. لا تكون بعض المجموعات الفرعية من السمات والمقاييس صالحة إلا في مجموعات معيّنة. لذلك، ننصحك بإنشاء التقارير في البداية باستخدام أداة إنشاء التقارير، ثم استنساخ هذه التقارير وتعديلها من خلال واجهة برمجة التطبيقات.

إعداد مرجع تقرير

تتمثّل الخطوة الأولى في إنشاء تقرير باستخدام "أداة إنشاء التقارير" أو تعديله في ضبط عنصر مصدر التقرير. إذا كنت بصدد إنشاء تقرير جديد، ستبدأ بمورد فارغ وتضبط الحقول اللازمة. إذا كنت بصدد تعديل تقرير حالي، يمكنك اختيار ما يلي:

1. مفضَّل: إجراء تحديث جزئي باستخدام هذا الأسلوب، ستبدأ بمورد فارغ وتضبط الحقول التي تريد تغييرها. لا يحفظ التعديل الجزئي سوى التغييرات التي تجريها على الحقول التي تحدّدها.
2. يتم إجراء تعديل كامل. باستخدام هذا الأسلوب، يمكنك تحميل مصدر تقرير حالي وتعديل حقوله مباشرةً. يحفظ التعديل الكامل دائمًا جميع حقول التقرير.

تختلف المحتويات الدقيقة لمورد التقرير حسب نوع التقرير الذي يتم إعداده. مع ذلك، هناك بعض الحقول المشتركة بين جميع أنواع التقارير:

الحقل	الوصف
الحقول المطلوبة
الاسم	اسم التقرير
النوع	نوع التقرير
الحقول الاختيارية
delivery	إعدادات تسليم التقرير عبر البريد الإلكتروني
fileName	اسم الملف المستخدَم عند إنشاء ملفات التقارير لهذا التقرير.
التنسيق	تنسيق الإخراج للتقرير، إما CSV أو Excel
الجدول الزمني	جدول زمني يُستخدَم لتنفيذ تقريرك بشكلٍ متكرّر.

تشكّل هذه الحقول الشائعة البنية الأساسية لتقريرك. يوضّح المثال أدناه كيفية إنشاء مورد تقرير عادي جديد:

#C

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

Python

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

Ruby

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

تحديد معايير التقرير

بعد اختيار نوع التقرير وإعداد الحقول الشائعة، تتمثّل الخطوة التالية في تحديد معايير التقرير. تُستخدَم معايير التقرير للحدّ من نطاق تقريرك، ما يضمن عرض المعلومات ذات الصلة فقط. ويحدّد أيضًا بنية ناتج التقرير.

تعتمد المعايير المستخدَمة على نوع التقرير. يتم توضيح العلاقة بين نوع التقرير والمعايير في الجدول التالي:

نوع التقرير	حقل المعايير
STANDARD	المعايير
تسجيل المواد الكيميائية وتقييمها واعتمادها وتقييدها (REACH)	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
FLOODLIGHT	floodlightCriteria
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

على الرغم من أنّ كل معيار من هذه المعايير الخاصة بنوع معيّن يعرض مجموعة مختلفة قليلاً من الحقول، هناك مجموعة من حقول المعايير الشائعة التي تكون مفيدة بشكل عام للتحكّم في ناتج التقرير:

الحقل	الوصف
dateRange	التواريخ التي يجب إنشاء هذا التقرير لها يمكن استخدامها لتحديد تاريخ بدء وتاريخ انتهاء مخصّصَين أو نطاق زمني نسبي. ملاحظة: عند إنشاء التقارير من خلال واجهة برمجة التطبيقات، يتم تحديد نطاقات التواريخ النسبية، مثل YESTERDAY، في المنطقة الزمنية لأمريكا/لوس أنجلوس. وقد يؤدي ذلك إلى نتائج غير متوقّعة للمستخدمين في مناطق زمنية مختلفة.
dimensionFilters	قائمة بالفلاتر التي تقيّد النتائج المعروضة راجِع قسم قيم فلتر طلب البحث للحصول على مزيد من المعلومات حول إعداد الفلاتر.
الأبعاد	قائمة بعناصر "مدير الحملة 360" التي سيتم تضمينها في ناتج التقرير
metricNames	وحدات القياس العادية التي سيتم تضمينها في ناتج التقرير.

اطّلِع على قسم تحديد توافق الحقول لمزيد من المعلومات عن اختيار السمات والمقاييس والفلاتر لتقريرك. يتم توضيح حقول المعايير الإضافية الخاصة بنوع معيّن في المستندات المرجعية ومركز المساعدة.

يضيف المثال أدناه معيارًا أساسيًا إلى مرجع التقرير العادي:

#C

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

Python

# 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

Ruby

# 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.

يحتوي طلب البحث الأساسي عن قيم السمات على اسم السمة، بالإضافة إلى تاريخ البدء وتاريخ الانتهاء. يقتصر الردّ على القيم الصالحة خلال تلك الفترة الزمنية. يمكن تحديد فلاتر إضافية إذا كنت بحاجة إلى تقييد نتائج طلب البحث بشكل أكبر.

يبحث المثال أدناه عن قيم فلتر المعلِن الصالحة خلال التواريخ التي سيتم فيها عرض تقريرنا، ويضيفها إلى معايير التقرير:

#C

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

Python

# 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]]

Ruby

# 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 لمعرفة الحقول الصالحة بالنظر إلى الحقول التي سبق أن اخترتها. سيتم تحليل إعدادات التقرير، وسيتم عرض ردّ يحتوي على السمات والمقاييس والفلاتر المتوافقة. بما أنّ الحقول في هذا الردّ ليست جميعها متوافقة مع بعضها البعض، قد تحتاج إلى تقديم طلبات متعدّدة لضمان عمل جميع الحقول التي تختارها معًا.

يوضّح المثال أدناه كيفية تقديم طلب نموذج للحقول المتوافقة، باستخدام مورد التقرير كإدخال:

#C

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

Python

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

Ruby

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:

#C

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

جافا

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

PHP

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

Python

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

Ruby

report = service.insert_report(profile_id, report)

إذا كنت تجري تعديلاً جزئيًا، يمكنك حفظ التغييرات من خلال استدعاء Reports.patch:

#C

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

Python

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

Ruby

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

أو، إذا قرّرت إجراء تعديل كامل، يمكنك حفظ التغييرات من خلال استدعاء Reports.update:

#C

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

Python

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

Ruby

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

بعد إرسال طلب حفظ ناجح، سيتم عرض نسخة من مصدر التقرير في نص الردّ. سيتضمّن هذا المرجع بعض الحقول الجديدة التي تم ملؤها، وأهمّها حقل المعرّف. هذا المعرّف هو ما ستستخدمه للإشارة إلى هذا التقرير في بقية سير عملك.