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

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

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

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

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

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

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

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

الحقل	الوصف
الحقول المطلوبة
الاسم	اسم التقرير
كتابة	نوع التقرير
الحقول الاختيارية
تسليم	إعدادات تسليم التقرير عبر البريد الإلكتروني
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";

Java

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

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

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

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

نوع التقرير	حقل المعايير
عادي	المعايير
تسجيل المواد الكيميائية وتقييمها واعتمادها وتقييدها (REACH)	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
الفيضانات	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;

Java

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

Java

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

Java

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

Java

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

Java

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

Java

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

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