Diese Seite wurde von der Cloud Translation API übersetzt.

Berichte erstellen und aktualisieren

Mit dem Berichtsdienst für die Campaign Manager 360 API können Sie Report Builder-Berichte mithilfe von Ressourcenobjekten für Berichte erstellen und aktualisieren. Eine Berichtsressource enthält grundlegende Informationen zu einem auszuführenden Bericht sowie die Struktur der Berichtsausgabe.

In diesem Leitfaden wird beschrieben, wie Sie Report Builder-Berichte programmatisch über den Berichtsdienst erstellen und aktualisieren.

Berichtsressource konfigurieren

Der erste Schritt beim Erstellen oder Aktualisieren eines Report Builder-Berichts besteht darin, ein Ressourcenobjekt für Berichte zu konfigurieren. 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:

Bevorzugt: Ein Teilupdate wird durchgeführt. Bei diesem Ansatz beginnen Sie mit einer leeren Ressource und legen die Felder fest, die Sie ändern möchten. Bei einer teilweisen Aktualisierung werden nur Änderungen an den von Ihnen angegebenen Feldern gespeichert.
Ein vollständiges Update wird durchgeführt. Auf diese Weise laden Sie eine vorhandene Berichtsressource und ändern direkt ihre Felder. Bei einer vollständigen Aktualisierung 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 E-Mail-Zustellungseinstellungen des Berichts.
fileName	Der Dateiname, der beim Erstellen von Berichtsdateien für diesen Bericht verwendet wird.
Format	Das Ausgabeformat des Berichts, entweder CSV oder Excel.
Zeitplan	Ein Zeitplan, der zur regelmäßigen Erstellung eines Berichts verwendet wird.

Diese gemeinsamen Felder bilden das Grundgerüst Ihres Berichts. Im folgenden Beispiel sehen Sie, wie eine neue Standardberichtsressource erstellt wird:

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 allgemeine Felder konfiguriert haben, müssen Sie im nächsten Schritt die Berichtskriterien definieren. Die Berichtskriterien werden verwendet, um den Umfang Ihres Berichts einzuschränken, sodass sichergestellt wird, dass nur relevante Informationen zurückgegeben werden. Außerdem wird die Struktur der Berichtsausgabe definiert.

Die verwendeten Kriterien hängen von der Art des Berichts ab. Die Beziehung zwischen Berichtstyp und Kriterien wird in der folgenden Tabelle erläutert:

Berichtstyp	Kriterienfeld
STANDARD	Kriterien
REACH	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
FLOODLIGHT	floodlightCriteria
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

Während jedes dieser typspezifischen Kriterien einen etwas anderen Satz von Feldern beinhaltet, gibt es eine Reihe von allgemeinen Kriterienfeldern, die im Allgemeinen für die Steuerung der Berichtsausgabe nützlich sind:

Feld	Beschreibung
dateRange	Der Zeitraum, für den dieser Bericht ausgeführt werden soll. Hiermit können Sie entweder ein benutzerdefiniertes Start- und Enddatum oder einen relativen Zeitraum angeben. Hinweis:Wenn Sie Berichte über die API erstellen, werden relative Zeiträume wie `YESTERDAY` in der Zeitzone „Amerika/Los Angeles“ angegeben. Das kann bei Nutzern in verschiedenen Zeitzonen zu unerwarteten Ergebnissen führen.
dimensionFilters	Eine Liste von Filtern, die die zurückgegebenen Ergebnisse einschränken. Weitere Informationen zum Konfigurieren von Filtern finden Sie im Abschnitt Abfragefilterwerte.
Dimensionen	Eine Liste der Campaign Manager 360-Elemente, die in die Ausgabe des Berichts einbezogen werden sollen.
metricNames	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 Feldkompatibilität bestimmen. Weitere typspezifische Kriterienfelder werden in der Referenzdokumentation und in der Hilfe erläutert.

Im folgenden Beispiel wird unserer Standardberichtsressource ein grundlegendes Kriterium 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

Abfragefilterwerte

Wenn Sie Filter für einen Bericht konfigurieren, müssen Sie die genauen Werte angeben, die die Filter zur Einschränkung der Berichtsausgabe verwenden. Wenn Sie die möglichen Werte für einen bestimmten Filter nicht kennen, können Sie den Dienst DimensionValues verwenden.

Eine einfache Abfrage für Dimensionswerte enthält einen Dimensionsnamen sowie ein Startdatum und ein Enddatum. Das Start- und Enddatum beschränkt die Antwort auf Werte, die innerhalb dieses Zeitraums gültig sind. Zusätzliche Filter können angegeben werden, wenn Sie die Abfrageergebnisse weiter einschränken müssen.

Im folgenden Beispiel werden für den Zeitraum, in dem der Bericht erstellt wird, gültige Werbetreibendenfilterwerte 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 ermitteln

Bei der Konfiguration der Berichtskriterien ist zu beachten, dass nicht alle Kombinationen aus Kennzahlen, Dimensionen und Filtern gültig sind. Sie dürfen keinen Bericht speichern, der eine ungültige Kombination enthält. Daher ist es wichtig, dass die Felder, die Sie verwenden möchten, miteinander kompatibel sind.

Wenn Sie Ihre Berichtsressource erstellen, können Sie sie an den Dienst Reports.compatibleFields übergeben. So sehen Sie, welche Felder in Anbetracht der bereits ausgewählten Felder gültig sind. Die Konfiguration des Berichts wird analysiert und eine Antwort mit den kompatiblen Dimensionen, Messwerten und Filtern wird zurückgegeben. Da nicht alle Felder in dieser Antwort miteinander kompatibel sind, müssen Sie möglicherweise mehrere Anfragen stellen, um sicherzustellen, dass alle ausgewählten Felder zusammenwirken.

Das folgende Beispiel zeigt, wie Sie eine Beispielanfrage für kompatible Felder stellen, indem Sie unsere Berichtsressource als Eingabe verwenden:

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 speichern Sie die Berichtsressource. Wenn Sie einen neuen Bericht erstellen, können Sie ihn durch einen 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 eine Teilaktualisierung durchführen, können Sie die Änderungen durch Aufrufen von Reports.patch speichern:

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 durchführen möchten, können Sie die Ä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. Bei dieser Ressource werden einige neue Felder ausgefüllt. Das wichtigste ist das id-Feld. Mit dieser ID verwenden Sie während des restlichen Workflows diesen Bericht.

Berichte erstellen und aktualisieren Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Berichtsressource konfigurieren

C#

Java

PHP

Python

Ruby

Berichtskriterien definieren

C#

Java

PHP

Python

Ruby

Abfragefilterwerte

C#

Java

PHP

Python

Ruby

Feldkompatibilität ermitteln

C#

Java

PHP

Python

Ruby

Bericht speichern

C#

Java

PHP

Python

Ruby

C#

Java

PHP

Python

Ruby

C#

Java

PHP

Python

Ruby

Berichte erstellen und aktualisieren