Tworzenie i aktualizowanie raportów

Usługa Raporty dla interfejsu Campaign Manager 360 API umożliwia tworzenie i aktualizowanie raportów w Kreatorze raportów przy użyciu obiektów zasobów raportu. Zasób raportu zawiera podstawowe informacje o tym, jaki raport ma zostać wygenerowany, oraz strukturę raportu.

Ten przewodnik zawiera szczegółowe informacje na temat automatycznego tworzenia i aktualizowania raportów w Kreatorze raportów za pomocą usługi Raporty.

Uwaga: przygotowanie prawidłowego raportu nie jest zadaniem łatwym. Niektóre podzbiory wymiarów i danych są prawidłowe tylko w określonych kombinacjach. Dlatego zalecamy początkowo tworzenie raportów za pomocą Kreatora raportów, a następnie ich kopiowanie i modyfikowanie przez interfejs API.

Konfigurowanie zasobu raportu

Pierwszym krokiem przy tworzeniu lub aktualizowaniu raportu w Kreatorze raportów jest skonfigurowanie obiektu zasobu raportu. Jeśli tworzysz nowy raport, zacznij od pustego zasobu i ustawisz wymagane pola. Podczas aktualizowania istniejącego raportu masz do wyboru te opcje:

1. Preferowana: wprowadzanie częściowej aktualizacji. Ta metoda pozwoli Ci utworzyć pusty zasób i ustawić pola, które chcesz zmienić. Częściowa aktualizacja zapisuje tylko zmiany w wybranych polach.
2. Przeprowadzam pełną aktualizację. Ta metoda pozwala wczytać istniejący zasób raportu i bezpośrednio zmodyfikować jego pola. Pełna aktualizacja powoduje zapisanie wszystkich pól raportu.

Dokładna zawartość zasobu raportu zależy od konfigurowanego typu raportu. Mimo to istnieje kilka pól wspólnych dla wszystkich typów raportów:

Pole	Opis
Pola wymagane
name	Nazwa raportu.
typ	Typ raportu.
Pola opcjonalne
dostarczanie	Ustawienia dostarczania e-maili z raportem.
Nazwa pliku	Nazwa pliku używana podczas generowania plików raportu.
reklamy	Format wyjściowy raportu – CSV lub Excel.
harmonogram	Harmonogram generowania raportu cyklicznego.

Te wspólne pola tworzą szkielet raportu. Poniższy przykład pokazuje, jak utworzyć nowy standardowy zasób raportu:

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

Definiowanie kryteriów raportu

Następnym krokiem po wybraniu typu raportu i skonfigurowaniu wspólnych pól jest zdefiniowanie kryteriów raportu. Kryteria raportu są wykorzystywane do ograniczenia zakresu raportu, tak aby wyświetlane były tylko istotne informacje. Określa też strukturę wyników raportu.

Użyte kryteria zależą od typu raportu. Relację między typem raportu a kryteriami znajdziesz w tej tabeli:

Typ raportu	Pole kryteriów
STANDARDOWY	kryterium
REACH	reachCriteria
ŚCIEŻKA_KONWERSJI	pathToConversionCriteria
FLOODLIGHT	Kryteria Floodlight
CROSS_DIMENSION_REACH (CROSS_DIMENSION_REACH)	crosswymiarReachCriteria

Mimo że każde z tych kryteriów uwzględnia nieco inny zestaw pól, istnieje zestaw typowych pól, które przydają się zazwyczaj do kontrolowania danych wyjściowych z raportu:

Pole	Opis
zakres dat	Daty, w których raport ma być generowany. Możesz jej użyć, by określić niestandardową datę rozpoczęcia i zakończenia lub względny zakres dat. Uwaga: w przypadku generowania raportów za pomocą interfejsu API względne zakresy dat, takie jak YESTERDAY, są rozpoznawane w strefie czasowej Ameryki/Los Angeles. Może to powodować nieoczekiwane wyniki w przypadku użytkowników znajdujących się w różnych strefach czasowych.
filtry wymiarów,	Lista filtrów, które ograniczają wyświetlane wyniki. Więcej informacji o konfigurowaniu filtrów znajdziesz w sekcji Wartości filtrów zapytań.
wymiary	Lista elementów Campaign Managera 360, które zostaną uwzględnione w wynikach raportu.
Nazwy danych	Standardowe jednostki miary, które zostaną uwzględnione w danych wyjściowych raportu.

Więcej informacji o wybieraniu wymiarów, danych i filtrów w raporcie znajdziesz w sekcji o określaniu zgodności pól. Dodatkowe pola kryteriów poszczególnych typów znajdziesz w dokumentacji i w Centrum pomocy.

Przykład poniżej dodaje podstawowe kryteria do naszego standardowego zasobu raportu:

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

Wartości filtra zapytań

Podczas konfigurowania filtrów raportu musisz określić dokładne wartości, których będą one używały, aby ograniczyć dane wyjściowe. Jeśli nie masz pewności, jakie są możliwe wartości konkretnego filtra, wyszukaj je za pomocą usługi DimensionsValues.

Zapytanie o wartości wymiaru podstawowego zawiera nazwę wymiaru, a także datę rozpoczęcia i datę zakończenia. Daty rozpoczęcia i zakończenia ograniczają odpowiedź na wartości prawidłowe w danym okresie. Jeśli chcesz jeszcze bardziej ograniczyć wyniki zapytania, możesz użyć dodatkowych filtrów.

Poniższy przykład pokazuje prawidłowe wartości filtra reklamodawców w okresach, w których raport będzie uruchamiany, i dodaje je do kryteriów raportu:

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

Określ zgodność z polami

Podczas konfigurowania kryteriów raportu pamiętaj, że nie wszystkie kombinacje danych, wymiarów i filtrów są prawidłowe. Nie możesz zapisać raportu zawierającego nieprawidłową kombinację, dlatego ważne jest, aby pola, których zamierzasz używać, były ze sobą zgodne.

Gdy tworzysz zasób raportu, możesz go przekazać do usługi Reports.compatibleFields, by sprawdzić, które pola są prawidłowe w przypadku wybranych już pól. Zostanie przeanalizowana konfiguracja raportu. Zostanie zwrócona odpowiedź zawierająca zgodne wymiary, dane i filtry. Nie wszystkie pola w tej odpowiedzi będą ze sobą zgodne, dlatego aby mieć pewność, że wszystkie pola będą ze sobą działać, konieczne może być przesłanie wielu próśb.

Przykład poniżej pokazuje, jak wysłać żądanie przykładowego zgodnego pola, korzystając z zasobu raportu:

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

Zapisz raport

Ostatnim etapem tego procesu jest zapisanie zasobu raportu. Jeśli tworzysz nowy raport, możesz go wstawić do wywołania Report.insert:

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)

Jeśli wprowadzasz częściową aktualizację, możesz zapisać zmiany, wywołując metodę Reports.patch:

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)

Jeśli zdecydujesz się przeprowadzić pełną aktualizację, możesz zapisać zmiany, wywołując Raporty.update:

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

Po pomyślnym zapisaniu żądania kopia zasobu raportu zostanie zwrócona w treści odpowiedzi. Ten zasób będzie zawierać kilka nowych pól, z których najważniejsze to pole identyfikatora. Identyfikator, którego będziesz używać do odwoływania się do tego raportu w pozostałych pozostałych przepływach pracy.