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

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

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

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

ضبط مورد للتقرير

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

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

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

الحقل	الوصف
الحقول المطلوبة
اسم	اسم التقرير.
كتابة	نوع التقرير
الحقول الاختيارية
تسليم	إعدادات تسليم البريد الإلكتروني للتقرير.
اسم الملف	اسم الملف المستخدَم عند إنشاء ملفات التقرير لهذا التقرير.
التنسيق	تنسيق الناتج للتقرير، إما بتنسيق 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");

‫2,999

$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)	مدى الوصول إلى الجمهور
PATH_TO_CONVERSION	pathToConversionSpecification
الفيضان	معايير Floodlight
CROSS_DIMENSION_REACH	cross تمتلك مدى الوصول

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

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

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

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

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

‫2,999

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

‫2,999

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

‫2,999

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

‫2,999

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

‫2,999

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

‫2,999

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

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