Campaign Manager 360 API v4 को बंद करने की तय तारीख आ गई है. तुरंत v5 पर माइग्रेट करें.

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

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

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

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

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

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

रिपोर्ट रिसॉर्स का कॉन्टेंट, कॉन्फ़िगर की जा रही रिपोर्ट के टाइप के हिसाब से अलग-अलग होता है. हालांकि, कुछ फ़ील्ड ऐसे होते हैं जो सभी तरह की रिपोर्ट में मौजूद होते हैं:

फ़ील्ड	ब्यौरा
ज़रूरी फ़ील्ड
नाम	रिपोर्ट का नाम.
टाइप	रिपोर्ट किस तरह की है.
ज़रूरी नहीं हैं
डिलीवरी	रिपोर्ट को ईमेल से भेजने की सेटिंग.
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	मानदंड
आरईएसीएच (रीच)	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
FLOODLIGHT	floodlightCriteria
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

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

फ़ील्ड	ब्यौरा
dateRange	वे तारीखें जिनके लिए यह रिपोर्ट जनरेट की जानी चाहिए. इसका इस्तेमाल, शुरू और खत्म होने की तारीख या तुलनात्मक तारीख की सीमा तय करने के लिए किया जा सकता है. ध्यान दें: एपीआई के ज़रिए रिपोर्ट जनरेट करते समय, तारीख की रिलेटिव रेंज, जैसे कि `YESTERDAY` को अमेरिका/लॉस एंजेलिस के टाइम ज़ोन में हल किया जाता है. इस वजह से, अलग-अलग टाइम ज़ोन में मौजूद उपयोगकर्ताओं को उम्मीद से अलग नतीजे मिल सकते हैं.
dimensionFilters	ऐसे फ़िल्टर की सूची जो मिले हुए नतीजों को सीमित करते हैं. फ़िल्टर कॉन्फ़िगर करने के बारे में ज़्यादा जानकारी के लिए, क्वेरी फ़िल्टर की वैल्यू सेक्शन देखें.
आयाम	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.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);

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