Berichte erstellen und aktualisieren

Mit dem Berichtsdienst für die Campaign Manager 360 API können Sie Report Builder-Berichte mit Berichtsressourcenobjekten erstellen und aktualisieren. In einer Berichtsressource werden grundlegende Informationen zu einem Bericht sowie die Struktur der Berichtsausgabe umrissen.

In diesem Leitfaden wird detailliert beschrieben, wie Report Builder-Berichte programmatisch über den Berichtsdienst erstellt und aktualisiert werden.

Hinweis: Einen gültigen Bericht zu erstellen, ist keine leichte Aufgabe. Einige Teilmengen von Dimensionen und Messwerten sind nur in bestimmten Kombinationen gültig. Wir empfehlen daher, Berichte zuerst mit Report Builder zu erstellen und dann über die API zu klonen und zu ändern.

Berichtsressource konfigurieren

Der erste Schritt beim Erstellen oder Aktualisieren eines Report Builder-Berichts besteht in der Konfiguration eines Berichtsressourcenobjekts. Wenn Sie einen neuen Bericht erstellen, beginnen Sie mit einer leeren Ressource und legen die erforderlichen Felder fest. Wenn Sie einen vorhandenen Bericht aktualisieren, haben Sie folgende Möglichkeiten:

1. Bevorzugt: Teilweise Aktualisierung. Bei diesem Ansatz beginnen Sie mit einer leeren Ressource und legen die Felder fest, die geändert werden sollen. Bei einer Teilaktualisierung werden nur die Änderungen an den von Ihnen angegebenen Feldern gespeichert.
2. Vollständiges Update Bei diesem Ansatz wird eine vorhandene Berichtsressource geladen und die Felder werden direkt geändert. Bei einem vollständigen Update werden immer alle Felder des Berichts gespeichert.

Der genaue Inhalt einer Berichtsressource hängt vom Berichtstyp ab, den Sie konfigurieren. Dennoch gibt es einige Felder, die in allen Berichtstypen gleich sind:

Feld	Beschreibung
Pflichtfelder
name	Der Name des Berichts.
Typ	Der Typ des Berichts.
Optionale Felder
Übermittlung	Die Einstellungen für die E-Mail-Zustellung des Berichts
Dateiname	Der Dateiname, der beim Generieren der Berichtsdateien für diesen Bericht verwendet wird.
Format	Das Ausgabeformat des Berichts, entweder CSV oder Excel.
Zeitplan	Ein Zeitplan für die regelmäßige Generierung eines Berichts.

Diese gemeinsamen Felder bilden das Gerüst Ihres Berichts. Im folgenden Beispiel wird eine neue Standardberichtsressource erstellt:

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

Berichtskriterien definieren

Nachdem Sie einen Berichtstyp ausgewählt und gemeinsame Felder konfiguriert haben, müssen Sie als Nächstes die Berichtskriterien definieren. Mithilfe der Berichtskriterien wird der Umfang des Berichts begrenzt, sodass nur relevante Informationen zurückgegeben werden. Außerdem wird die Struktur der Berichtsausgabe definiert.

Welche Kriterien verwendet werden, hängt vom Berichtstyp ab. Die Beziehung zwischen Berichtstyp und Kriterien wird in der folgenden Tabelle erläutert:

Berichtstyp	Feld „Kriterien“
STANDARD	Kriterien
REACH	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
FLOODLIGHT	Hochwasserkriterien
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

Während jedes dieser typspezifischen Kriterien eine etwas andere Gruppe von Feldern beinhaltet, gibt es eine Reihe allgemeiner Kriterienfelder, die im Allgemeinen zur Steuerung der Berichtsausgabe nützlich sind:

Feld	Beschreibung
dateRange	Der Zeitraum, für den dieser Bericht erstellt werden soll. Sie können entweder ein benutzerdefiniertes Start- und Enddatum oder einen relativen Zeitraum angeben. Hinweis:Bei der Berichterstellung über die API werden relative Zeiträume wie YESTERDAY in der Zeitzone „Amerika/Los Angeles“ aufgelöst. Das kann für Nutzer in verschiedenen Zeitzonen zu unerwarteten Ergebnissen führen.
DimensionsFilter	Eine Liste von Filtern, die die zurückgegebenen Ergebnisse einschränken. Weitere Informationen zum Konfigurieren von Filtern finden Sie im Abschnitt Werte für die Abfragefilter.
Dimensionen	Eine Liste der Campaign Manager 360-Elemente, die in der Berichtsausgabe enthalten sein sollen.
Messwertnamen	Standardmaßeinheiten, die in die Berichtsausgabe aufgenommen werden sollen.

Weitere Informationen zur Auswahl von Dimensionen, Messwerten und Filtern für Ihren Bericht finden Sie im Abschnitt Kompatibilität mit Feldern bestimmen. Weitere Felder für typspezifische Kriterien finden Sie in der Referenzdokumentation und in der Hilfe.

Im folgenden Beispiel werden unserer Standardberichtsressource grundlegende Kriterien hinzugefügt:

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

Filterwerte abfragen

Wenn Sie Filter für einen Bericht konfigurieren, müssen Sie genau die Werte angeben, die von den Filtern zur Einschränkung der Berichtsausgabe verwendet werden. Wenn Sie nicht sicher sind, welche Werte für einen bestimmten Filter möglich sind, können Sie sie mit dem Dienst DimensionsValues suchen.

Eine einfache Abfrage für Dimensionswerte enthält einen Dimensionsnamen sowie ein Startdatum und ein Enddatum. Mit dem Start- und Enddatum wird die Antwort auf Werte begrenzt, die innerhalb dieses Zeitraums gültig sind. Wenn Sie die Abfrageergebnisse weiter eingrenzen möchten, können Sie zusätzliche Filter angeben.

Im folgenden Beispiel werden gültige Filterwerte für Werbetreibende während der Zeiträume des Berichts ermittelt und den Berichtskriterien hinzugefügt:

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

Feldkompatibilität bestimmen

Denken Sie beim Konfigurieren der Berichtskriterien daran, dass nicht alle Kombinationen aus Messwerten, Dimensionen und Filtern gültig sind. Es ist nicht zulässig, einen Bericht zu speichern, der eine ungültige Kombination enthält. Daher ist es wichtig, dass die von Ihnen verwendeten Felder miteinander kompatibel sind.

Wenn Sie die Berichtsressource erstellen, können Sie sie an den Dienst Reports.compatibleFields übergeben, um zu sehen, welche Felder gültig sind. Daraufhin wird die Konfiguration des Berichts analysiert und eine Antwort mit den kompatiblen Dimensionen, Messwerten und Filtern zurückgegeben. Da nicht alle Felder in dieser Antwort garantiert miteinander kompatibel sind, müssen Sie möglicherweise mehrere Anfragen stellen, damit alle ausgewählten Felder miteinander funktionieren.

Das folgende Beispiel zeigt, wie Sie mit unserer Berichtsressource als Beispiel eine Anfrage für kompatible Felder stellen:

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

Bericht speichern

Im letzten Schritt wird dabei die Berichtsressource gespeichert. Wenn Sie einen neuen Bericht erstellen, können Sie ihn mit einem Aufruf von Reports.insert einfügen:

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)

Wenn Sie ein teilweises Update durchführen, können Sie Ihre Änderungen speichern, indem Sie Reports.patch aufrufen:

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)

Wenn Sie ein vollständiges Update ausführen möchten, können Sie Ihre Änderungen speichern, indem Sie Reports.update aufrufen:

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

Nach einer erfolgreichen Speicheranfrage wird eine Kopie der Berichtsressource im Antworttext zurückgegeben. Für diese Ressource werden einige neue Felder ausgefüllt. Das wichtigste davon ist das id-Feld. Auf diese ID lässt sich während des gesamten Workflows dieser Bericht verweisen.