Rapor Oluşturma ve Güncelleme

Campaign Manager 360 API'nin Raporlar hizmeti, rapor kaynak nesnelerini kullanarak Rapor Oluşturucu raporları oluşturmanıza ve güncellemenize olanak tanır. Rapor kaynağı, çalıştırılacak raporla ilgili temel bilgilerin yanı sıra rapor çıktısının yapısını da özetler.

Bu kılavuzda, Raporlar hizmeti aracılığıyla Rapor Oluşturucu raporlarının programlı olarak nasıl oluşturulacağı ve güncelleneceği açıklanmaktadır.

Not: Geçerli bir rapor oluşturmak önemsiz bir görev değildir. Bazı boyut ve metrik alt kümeleri yalnızca belirli kombinasyonlarda geçerlidir. Bu nedenle, raporları başlangıçta Rapor Oluşturucu ile oluşturmanızı, ardından bu raporları API aracılığıyla klonlayıp değiştirmenizi öneririz.

Rapor kaynağı yapılandırma

Rapor Oluşturucu raporu oluşturmanın veya güncellemenin ilk adımı, rapor kaynak nesnesini yapılandırmaktır. Yeni bir rapor oluşturuyorsanız boş bir kaynakla başlar ve gerekli alanları ayarlarsınız. Mevcut bir raporu güncelliyorsanız aşağıdakilerden birini yapabilirsiniz:

1. Tercih edilen: Kısmi güncelleme yapılır. Bu yaklaşımı kullanarak boş bir kaynakla başlar ve değiştirmek istediğiniz alanları ayarlarsınız. Kısmi güncelleme yalnızca belirttiğiniz alanlardaki değişiklikleri kaydeder.
2. Tam güncelleme yapılıyor. Bu yaklaşımı kullanarak mevcut bir rapor kaynağını yükler ve alanlarını doğrudan değiştirirsiniz. Tam güncelleme her zaman raporun tüm alanlarını kaydeder.

Bir rapor kaynağının tam içeriği, yapılandırdığınız rapor türüne bağlı olarak değişiklik gösterir. Buna rağmen tüm rapor türlerinde ortak olan birkaç alan vardır:

Alan	Açıklama
Zorunlu alanlar
ad	Raporun adı.
tür	Raporun türü.
İsteğe bağlı alanlar
eve teslimat	Raporun e-posta teslim ayarları.
fileName	Bu rapor için rapor dosyaları oluşturulurken kullanılan dosya adı.
format	Raporun çıktı biçimi (CSV veya Excel).
program	Raporunuzu düzenli olarak çalıştırmak için kullanılan bir program.

Bu ortak alanlar raporunuzun iskeletini oluşturur. Aşağıdaki örnekte yeni bir standart rapor kaynağının oluşturulması gösterilmektedir:

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

Rapor ölçütlerini tanımlayın

Rapor türünü seçip ortak alanları yapılandırdıktan sonraki adım rapor ölçütlerini tanımlamaktır. Rapor ölçütleri, yalnızca alakalı bilgilerin döndürülmesini sağlayarak raporunuzun kapsamını sınırlandırmak için kullanılır. Ayrıca rapor çıkışının yapısını da tanımlar.

Kullanılan ölçütler, raporun türüne bağlıdır. Rapor türü ile ölçütler arasındaki ilişki aşağıdaki tabloda açıklanmıştır:

Rapor türü	Ölçüt alanı
STANDART	ölçütler
REACH	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
FLOODLIGHT	floodlightCriteria
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

Bu türe özgü ölçütlerin her biri, biraz farklı alan grupları ortaya çıkarsa da rapor çıktısını kontrol etmek için genellikle yararlı olan bir dizi ortak ölçüt alanı bulunur:

Alan	Açıklama
dateRange	Bu raporun çalıştırılacağı tarihler. Özel bir başlangıç ve bitiş tarihini veya göreli bir tarih aralığını belirtmek için kullanılabilir. Not: API aracılığıyla raporlar çalıştırırken YESTERDAY gibi göreli tarih aralıkları Amerika/Los Angeles saat diliminde çözümlenir. Bu durum, farklı saat dilimlerindeki kullanıcılar için beklenmedik sonuçlara yol açabilir.
dimensionFilters	Döndürülen sonuçları kısıtlayan filtrelerin listesi. Filtreleri yapılandırma hakkında daha fazla bilgi edinmek için sorgu filtresi değerleri bölümünü inceleyin.
boyutlar	Rapor çıktısına dahil edilecek Campaign Manager 360 öğelerinin listesi.
metricNames	Rapor çıktısına dahil edilecek standart ölçü birimleri.

Raporunuzda boyutları, metrikleri ve filtreleri seçme hakkında daha fazla bilgi için alan uyumluluğunu belirleme bölümüne bakın. Türe özel ek ölçüt alanları, referans belgelerinde ve yardım merkezinde açıklanmıştır.

Aşağıdaki örnekte, standart rapor kaynağımıza bir temel ölçüt eklenmiştir:

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

Sorgu filtresi değerleri

Bir rapor için filtreleri yapılandırırken filtrelerin rapor çıkışını kısıtlamak için kullanacağı değerleri tam olarak belirtmeniz gerekir. Belirli bir filtre için olası değerlerin ne olduğundan emin değilseniz DimensionValues hizmetini kullanarak bu değerleri arayabilirsiniz.

Temel boyut değerleri sorgusu, boyut adı ile başlangıç tarihi ve bitiş tarihi içerir. Başlangıç ve bitiş tarihleri, yanıtı bu dönem içinde geçerli olan değerlerle sınırlar. Sorgu sonuçlarını daha fazla sınırlamanız gerekirse ek filtreler belirtilebilir.

Aşağıdaki örnek, raporumuzun çalıştırılacağı tarihlerdeki geçerli reklamveren filtresi değerlerini arar ve bunları rapor ölçütlerine ekler:

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

Alan uyumluluğunu belirleme

Rapor ölçütlerinizi yapılandırırken tüm metrik, boyut ve filtre kombinasyonlarının geçerli olmadığını unutmamanız önemlidir. Geçersiz kombinasyon içeren bir raporu kaydetmenize izin verilmez. Bu nedenle, kullanmayı planladığınız alanların birbirleriyle uyumlu olduğundan emin olmanız önemlidir.

Rapor kaynağınızı oluştururken, seçtiğiniz alanlara göre hangi alanların geçerli olduğunu görmek için bu kaynağı Reports.compatibleFields hizmetine aktarabilirsiniz. Raporun yapılandırması analiz edilecek ve uyumlu boyutları, metrikleri ve filtreleri içeren bir yanıt döndürülür. Bu yanıttaki alanların tümünün birbiriyle uyumlu olacağı garanti edilmediğinden, seçtiğiniz tüm alanların birlikte çalıştığından emin olmak için birden fazla istekte bulunmanız gerekebilir.

Aşağıdaki örnekte, rapor kaynağımızı giriş olarak kullanarak uyumlu bir alan isteğinin nasıl yapılacağı gösterilmektedir:

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

Raporu kaydedin

Bu süreçteki son adım, rapor kaynağınızı kaydetmektir. Yeni bir rapor oluşturuyorsanız Reports.insert'e bir çağrıyla bu raporu ekleyebilirsiniz:

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)

Kısmi bir güncelleme yapıyorsanız Reports.patch dosyasını çağırarak değişikliklerinizi kaydedebilirsiniz:

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)

Tam güncelleme yapmaya karar verdiyseniz Reports.update değerini çağırarak değişikliklerinizi kaydedebilirsiniz:

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

Başarılı bir kaydetme isteği sonrasında, yanıt gövdesinde rapor kaynağının bir kopyası döndürülür. Bu kaynakta birkaç yeni alan doldurulur. Bunlardan en önemlisi id alanıdır. Bu kimlik, iş akışınızın geri kalanında bu rapora başvurmak için kullanacağınız kimliktir.