रिपोर्ट बनाना और अपडेट करना

Campaign Manager 360 API के लिए, रिपोर्ट की सेवा का इस्तेमाल करके, रिपोर्ट रिसॉर्स ऑब्जेक्ट का इस्तेमाल करके Report Builder की रिपोर्ट बनाई और अपडेट की जा सकती हैं. रिपोर्ट रिसॉर्स में, रिपोर्ट चलाने के बारे में बुनियादी जानकारी के साथ-साथ, रिपोर्ट के आउटपुट का स्ट्रक्चर भी बताया जाता है.

इस गाइड में, रिपोर्ट की सेवा की मदद से, प्रोग्राम के ज़रिए Report Builder की रिपोर्ट बनाने और अपडेट करने का तरीका बताया गया है.

ध्यान दें: मान्य रिपोर्ट बनाना आसान काम नहीं है. डाइमेंशन और मेट्रिक के कुछ सबसेट, सिर्फ़ खास कॉम्बिनेशन में मान्य होते हैं. इसलिए, हमारा सुझाव है कि आप सबसे पहले Report Builder की मदद से रिपोर्ट बनाएं. इसके बाद, एपीआई की मदद से इन रिपोर्ट को क्लोन करें और उनमें बदलाव करें.

रिपोर्ट रिसॉर्स कॉन्फ़िगर करना

Report Builder की रिपोर्ट बनाने या अपडेट करने के लिए, सबसे पहले रिपोर्ट रिसॉर्स ऑब्जेक्ट को कॉन्फ़िगर करना होता है. नई रिपोर्ट बनाने के लिए, आपको खाली रिसॉर्स से शुरुआत करनी होगी और ज़रूरी फ़ील्ड सेट करने होंगे. मौजूदा रिपोर्ट को अपडेट करने के लिए, आपके पास ये विकल्प हैं:

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

रिपोर्ट के लिए मानदंड तय करना

रिपोर्ट का टाइप चुनने और सामान्य फ़ील्ड कॉन्फ़िगर करने के बाद, अगला चरण रिपोर्ट के लिए मानदंड तय करना है. रिपोर्ट के मानदंड का इस्तेमाल, रिपोर्ट के दायरे को सीमित करने के लिए किया जाता है. इससे यह पक्का किया जाता है कि सिर्फ़ काम की जानकारी दिखाई जाए. इससे रिपोर्ट के आउटपुट का स्ट्रक्चर भी तय होता है.

इस्तेमाल किए जाने वाले मानदंड, रिपोर्ट के टाइप पर निर्भर करते हैं. रिपोर्ट के टाइप और मानदंड के बीच का संबंध, यहां दी गई टेबल में बताया गया है:

रिपोर्ट का टाइप	मानदंड वाला फ़ील्ड
STANDARD	criteria
REACH	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
FLOODLIGHT	floodlightCriteria
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

इनमें से हर टाइप के हिसाब से तय किए गए मानदंड में, फ़ील्ड का थोड़ा अलग सेट दिखता है. हालांकि, सामान्य मानदंड वाले कुछ फ़ील्ड ऐसे होते हैं जो आम तौर पर रिपोर्ट के आउटपुट को कंट्रोल करने के लिए काम के होते हैं:

फ़ील्ड	ब्यौरा
dateRange	वे तारीखें जिनके लिए यह रिपोर्ट चलाई जानी चाहिए. इसका इस्तेमाल, अपनी पसंद के मुताबिक शुरू और खत्म होने की तारीख या तारीख की तुलना में तय की गई सीमा तय करने के लिए किया जा सकता है. ध्यान दें: एपीआई की मदद से रिपोर्ट चलाते समय, तारीख की तुलना में तय की गई सीमाएं, जैसे कि YESTERDAY, अमेरिका/लॉस ऐंजेलिस के टाइम ज़ोन में तय की जाती हैं. इससे अलग-अलग टाइम ज़ोन में मौजूद उपयोगकर्ताओं के लिए, उम्मीद से अलग नतीजे मिल सकते हैं.
dimensionFilters	फ़िल्टर की सूची. इससे दिखाए जाने वाले नतीजों को सीमित किया जाता है. फ़िल्टर कॉन्फ़िगर करने के बारे में ज़्यादा जानकारी के लिए, क्वेरी फ़िल्टर वैल्यू सेक्शन देखें.
dimensions	Campaign Manager 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 = datetime.date.today()
start_date = end_date - datetime.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=str(profile_id), body=report).execute()
)

Ruby

report = service.insert_report(profile_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);

सेव करने का अनुरोध पूरा होने के बाद, जवाब के मुख्य हिस्से में रिपोर्ट रिसॉर्स की एक कॉपी दिखेगी. इस रिसॉर्स में, कुछ नए फ़ील्ड भरे हुए दिखेंगे. इनमें से सबसे अहम फ़ील्ड, आईडी वाला फ़ील्ड है. इस आईडी का इस्तेमाल, अपने वर्कफ़्लो के बाकी हिस्सों में इस रिपोर्ट को रेफ़र करने के लिए किया जाएगा.