Rapor Oluşturma ve Güncelleme

Campaign Manager 360 API'sinin Raporlar hizmeti, rapor kaynağı nesnelerini kullanarak Rapor Oluşturucu raporları oluşturmanızı ve bunları güncellemenizi sağlar. Rapor kaynağı, çalıştırılacak bir 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 programatik olarak nasıl oluşturulacağı ve güncelleneceği açıklanmaktadır.

Not: Geçerli bir rapor oluşturmak basit bir iş değildir. Bazı boyut ve metrik alt kümeleri yalnızca belirli kombinasyonlarda geçerlidir. Dolayısıyla, ilk olarak Rapor Oluşturucu ile rapor oluşturmanızı ve bu raporları klonlayıp API aracılığıyla değiştirmenizi öneririz.

Rapor kaynağını yapılandırma

Rapor Oluşturucu raporu oluşturmanın veya güncellemenin ilk adımı, bir rapor kaynağı nesnesi yapılandırmaktır. Yeni bir rapor oluşturuyorsanız boş bir kaynakla başlayıp gerekli alanları ayarlarsınız. Mevcut bir raporu güncelliyorsanız şunları yapabilirsiniz:

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

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. Bununla birlikte, 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ı.
dosya adı	Bu rapor için rapor dosyaları oluşturulurken kullanılan dosya adı.
biçim	CSV veya Excel biçimindeki raporun çıkış biçimi.
program	Raporunuzu yinelenen bir şekilde çalıştırmak için kullanılan plandır.

Bu ortak alanlar, raporunuzun iskeletidir. Aşağıdaki örnekte yeni bir standart rapor kaynağı oluşturma 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");

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

Rapor ölçütlerini tanımlama

Bir rapor türü seçtikten ve ortak alanları yapılandırdıktan sonraki adım, rapor ölçütlerini tanımlamaktır. Rapor ölçütleri, raporunuzun kapsamını sınırlandırmak için kullanılır ve yalnızca alakalı bilgilerin döndürülmesini sağlar. Ayrıca, rapor çıktısı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	erişimÖlçütleri
PATH_TO_CONVERSION	pathToConversionÖlçütleri
FLOODLIGHT	floodlightÖlçüleri
CROSS_DIMENSION_REACH	crossBoyutErişim Kriterleri

Bu türe özgü ölçütlerin her biri biraz farklı bir alan grubunu açığa çıkarırken, genellikle rapor çıktısını kontrol etmek için yararlı olan bir dizi ortak ölçüt alanı vardır:

Alan	Açıklama
tarihAralığı	Bu raporun çalıştırılacağı tarihler. Özel bir başlangıç ve bitiş tarihi ya da göreli bir tarih aralığı belirtmek için kullanılabilir. Not: Raporları API üzerinden ç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 beklenmeyen sonuçlara neden olabilir.
boyutFiltreler	Döndürülen sonuçları kısıtlayan filtrelerin listesi. Filtreleri yapılandırma hakkında daha fazla bilgi için sorgu filtresi değerleri bölümüne bakın.
boyutlar	Rapor çıktısına dahil edilecek Campaign Manager 360 öğelerinin listesi.
metrikAdları	Rapor çıktısına dahil edilecek standart ölçü birimleri.

Raporunuz için boyut, metrik ve filtre seçme hakkında daha fazla bilgi edinmek üzere alan uyumluluğunu belirleme bölümünü inceleyin. Türe özgü ek ölçüt alanları referans dokümanlarda ve yardım merkezinde açıklanmıştır.

Aşağıdaki örnekte standart rapor kaynağımıza temel bir ö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);

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

Sorgu filtresi değerleri

Bir rapor için filtreleri yapılandırırken filtrelerin rapor çıktısını kısıtlamak için kullanacağı tam değerleri belirtmeniz gerekir. Belirli bir filtrenin olası değerlerinden emin değilseniz BoyutDeğerleri hizmetini kullanarak bunları arayın.

Temel boyut değerleri sorgusu, boyut adının yanı sıra başlangıç tarihi ve bitiş tarihi içerir. Başlangıç ve bitiş tarihleri, yanıtı bu dönemdeki geçerli değerlerle sınırlar. Sorgu sonuçlarını daha fazla sınırlandırmanız gerekiyorsa ek filtreler belirtilebilir.

Aşağıdaki örnekte, raporumuzun çalıştırılacağı tarihlerde geçerli reklamveren filtresi değerleri aranır ve değerler rapor ölçütlerine eklenir:

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

Alan uyumluluğunu belirleyin

Rapor ölçütlerinizi yapılandırırken tüm metrik, boyut ve filtre kombinasyonlarının geçerli olmadığını unutmayın. 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 alanları temel alarak hangi alanların geçerli olduğunu görmek için kaynağı Reports.UyumluFields hizmetine aktarabilirsiniz. Raporun yapılandırması analiz edilir ve uyumlu boyutlar, metrikler ve filtreler 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ışabilmesi için birden fazla istekte bulunmanız gerekebilir.

Aşağıdaki örnekte, giriş olarak rapor kaynağımız kullanılarak uyumlu alan örneklerinin nasıl oluşturulacağı 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());
}

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

Raporu kaydetme

Bu işlemdeki son adım, rapor kaynağınızı kaydetmektir. Yeni bir rapor oluşturuyorsanız Reports.insert çağrısıyla ekleyebilirsiniz:

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)

Kısmi bir güncelleme yapıyorsanız Reports.patch çağrısı yaparak 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();

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)

Tam güncelleme gerçekleştirmek istiyorsanız Reports.update çağrısı yaparak 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();

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

Başarılı bir kaydetme isteğinde bulunduktan sonra, rapor gövdesinin bir kopyası yanıt gövdesinde döndürülür. Bu kaynakta en önemlisi kimlik alanı olan birkaç yeni alan doldurulacak. Bu kimlik, iş akışınızın geri kalanında bu rapora başvurmak için kullanılır.