Berichte erstellen und aktualisieren

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

In dieser Anleitung wird beschrieben, wie Sie Berichte im Berichts-Generator programmatisch über den Reports-Dienst erstellen und aktualisieren.

Hinweis :Das Erstellen eines gültigen Berichts ist nicht einfach. Einige Teilmengen von Dimensionen und Messwerten sind nur in bestimmten Kombinationen gültig. Wir empfehlen daher, Berichte zuerst mit Report Builder zu erstellen und sie dann über die API zu klonen und zu ändern.

Berichtsressource konfigurieren

Der erste Schritt beim Erstellen oder Aktualisieren eines Report Builder-Berichts besteht darin, ein Berichtsressourcenobjekt 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:

1. Bevorzugt: Führen Sie ein partielles Update durch. Bei dieser Methode beginnen Sie mit einer leeren Ressource und legen die Felder fest, die Sie ändern möchten. Bei einer Teilaktualisierung werden nur Änderungen an den von Ihnen angegebenen Feldern gespeichert.
2. Ein vollständiges Update wird durchgeführt. Bei diesem Ansatz laden Sie eine vorhandene Berichtsressource und ändern ihre Felder direkt. Bei einer vollständigen Aktualisierung werden immer alle Felder des Berichts gespeichert.

Der genaue Inhalt einer Berichtsressource hängt vom Typ des Berichts ab, den Sie konfigurieren. Es gibt jedoch einige Felder, die für alle 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.
fileName	Der Dateiname, der beim Generieren von Berichtsdateien für diesen Bericht verwendet wird.
Format	Das Ausgabeformat des Berichts, entweder CSV oder Excel.
Zeitplan	Ein Zeitplan, der verwendet wird, um Ihren Bericht regelmäßig auszuführen.

Diese gemeinsamen Felder bilden das Grundgerüst Ihres Berichts. Im folgenden Beispiel wird die Erstellung einer neuen Standardberichtsressource veranschaulicht:

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 die Berichtskriterien definieren. Mit den Berichtskriterien wird der Umfang Ihres Berichts eingeschränkt, sodass nur relevante Informationen zurückgegeben werden. Außerdem wird die Struktur der Berichtsausgabe definiert.

Die verwendeten Kriterien hängen vom Berichtstyp 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

Jedes dieser typspezifischen Kriterien macht eine etwas andere Gruppe von Feldern verfügbar. Es gibt jedoch eine Reihe von gemeinsamen Kriterienfeldern, die im Allgemeinen nützlich sind, um die Berichtsausgabe zu steuern:

Feld	Beschreibung
dateRange	Die Datumsangaben, für die dieser Bericht erstellt werden soll. Kann verwendet werden, um entweder ein benutzerdefiniertes Start- und Enddatum oder einen relativen Zeitraum anzugeben. Hinweis:Wenn Sie Berichte über die API erstellen, werden relative Zeiträume wie YESTERDAY in der Zeitzone „America/Los Angeles“ aufgelöst. Dies kann zu unerwarteten Ergebnissen für Nutzer in verschiedenen Zeitzonen führen.
dimensionFilters	Eine Liste von Filtern, die die zurückgegebenen Ergebnisse einschränken. Weitere Informationen zum Konfigurieren von Filtern finden Sie im Abschnitt Filterwerte abfragen.
Dimensionen	Eine Liste der Campaign Manager 360-Elemente, die in die Berichtsausgabe aufgenommen werden sollen.
metricNames	Standardmaßeinheiten, die in die Berichtsausgabe aufgenommen werden sollen.

Weitere Informationen zum Auswählen von Dimensionen, Messwerten und Filtern für Ihren Bericht finden Sie im Abschnitt Feldkompatibilität ermitteln. Zusätzliche typspezifische Kriterienfelder werden in der Referenzdokumentation und in der Hilfe erläutert.

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

Filterwerte für Abfragen

Wenn Sie Filter für einen Bericht konfigurieren, müssen Sie die genauen Werte angeben, mit denen die Berichtsausgabe eingeschränkt werden soll. Wenn Sie sich nicht sicher sind, welche Werte für einen bestimmten Filter möglich sind, können Sie sie mit dem Dienst DimensionValues nachschlagen.

Eine einfache Abfrage für Dimensionswerte enthält einen Dimensionsnamen sowie ein Startdatum und ein Enddatum. Das Start- und Enddatum beschränken die Antwort auf Werte, die innerhalb dieses Zeitraums gültig sind. Bei Bedarf können Sie zusätzliche Filter angeben, um die Abfrageergebnisse weiter einzuschränken.

Im folgenden Beispiel werden gültige Filterwerte für Werbetreibende für die Zeiträume gesucht, in denen der Bericht ausgeführt wird, 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 es wichtig, dass nicht alle Kombinationen von Messwerten, Dimensionen und Filtern gültig sind. Ein Bericht mit einer ungültigen Kombination kann nicht gespeichert werden. Achten Sie daher darauf, 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, um zu sehen, welche Felder angesichts 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 die Felder in dieser Antwort nicht alle garantiert miteinander kompatibel sind, müssen Sie möglicherweise mehrere Anfragen stellen, um sicherzustellen, dass alle von Ihnen ausgewählten Felder zusammen funktionieren.

Im folgenden Beispiel wird veranschaulicht, wie Sie eine Anfrage für kompatible Felder mit unserer Berichtsressource als Eingabe 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

Der letzte Schritt in diesem Prozess ist das Speichern der Berichtsressource. 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 eine Teilaktualisierung vornehmen, können Sie Ihre Änderungen mit dem Aufruf 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 Ihre Änderungen mit dem Aufruf von Reports.update speichern:

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. Diese Ressource enthält einige neue Felder, von denen das id-Feld das wichtigste ist. Diese ID verwenden Sie im restlichen Workflow, um auf diesen Bericht zu verweisen.