Rapor Oluşturma ve Güncelleme

Campaign Manager 360 API'nin Raporlar hizmeti, rapor kaynağı nesnelerini kullanarak Rapor Oluşturucu raporları oluşturmanıza ve güncellemenize olanak tanır. 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 ayrıntılı olarak açıklanmaktadır.

Not: Geçerli bir rapor oluşturmak kolay bir iş değildir. Boyut ve metriklerin bazı alt kümeleri yalnızca belirli kombinasyonlarda geçerlidir. Bu nedenle, başlangıçta Rapor Oluşturucu ile raporlar oluşturmanızı, ardından bu raporları API üzerinden klonlayıp değiştirmenizi öneririz.

Rapor kaynağı yapılandırma

Rapor Oluşturucu raporu oluşturma veya güncelleme sürecinin ilk adımı, rapor kaynağı nesnesi 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 şunları yapabilirsiniz:

1. Tercih edilen: Kısmi güncelleme yapma. 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 gerçekleştirme Bu yaklaşımı kullanarak mevcut bir rapor kaynağını yükleyip alanlarını doğrudan değiştirebilirsiniz. Tam güncelleme, raporun tüm alanlarını her zaman kaydeder.

Rapor kaynağının tam içeriği, yapılandırdığınız rapor türüne bağlı olarak değişir. 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 teslimi ayarları.
fileName	Bu rapor için rapor dosyaları oluşturulurken kullanılan dosya adı.
biçim	Raporun çıkış biçimi (CSV veya Excel).
program	Raporunuzu yinelenen şekilde çalıştırmak için kullanılan bir plan.

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ımlama

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

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

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

Türe özgü bu ölçütlerin her biri biraz farklı bir alan grubu sunsa da rapor çıktısını kontrol etmek için genellikle yararlı olan bir dizi ortak ölçüt alanı vardır:

Alan	Açıklama
dateRange	Bu raporun çalıştırılması gereken tarihler. Özel bir başlangıç ve bitiş tarihi ya da göreli tarih aralığı belirtmek için kullanılabilir. Not: API üzerinden rapor oluştururken 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 neden olabilir.
dimensionFilters	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.
metricNames	Rapor çıktısına dahil edilecek standart ölçü birimleri.

Raporunuz için boyut, metrik ve filtre seçme hakkında daha fazla bilgi edinmek için alan uyumluluğunu belirleme bölümüne bakın. Türe özgü ek ölçüt alanları referans belgelerinde ve Yardım Merkezi'nde açıklanmaktadır.

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

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ğı tam değerleri belirtmeniz gerekir. Belirli bir filtrenin olası değerlerinden emin değilseniz DimensionValues hizmetini kullanarak bu değerleri arayın.

Temel bir 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 zaman aralığında geçerli olan değerlerle sınırlar. Sorgu sonuçlarını daha da sınırlamanız gerekiyorsa ek filtreler belirtebilirsiniz.

Aşağıdaki örnekte, raporumuzun yayınlanacağı tarihlerde geçerli reklamveren filtresi değerleri aranır ve 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);
}

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 metrik, boyut ve filtrelerin tüm kombinasyonlarının geçerli olmadığını unutmamak önemlidir. Geçersiz bir kombinasyon içeren raporu kaydetmenize izin verilmez. Bu nedenle, kullanmayı planladığınız alanların birbiriyle uyumlu olduğundan emin olmanız önemlidir.

Rapor kaynağınızı oluştururken, hangi alanların geçerli olduğunu görmek için bunu Reports.compatibleFields hizmetine iletebilirsiniz. Raporun yapılandırması analiz edilir 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ışmasını sağlamak için birden fazla istekte bulunmanız gerekebilir.

Aşağıdaki örnekte, rapor kaynağımızı giriş olarak kullanarak nasıl örnek uyumlu alanlar isteği 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());
}

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ürecin 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();

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 güncelleme yapıyorsanız Reports.patch'i ç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)

Alternatif olarak, tam güncelleme yapmaya karar verdiyseniz Reports.update'i ç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);

Kaydetme isteği başarılı olduktan sonra, yanıt gövdesinde rapor kaynağının bir kopyası döndürülür. Bu kaynakta, en önemlisi id alanı olmak üzere birkaç yeni alan doldurulmuş olacak. Bu kimlik, iş akışınızın geri kalanında bu rapora başvurmak için kullanacağınız kimliktir.