Tworzenie i aktualizowanie raportów

Usługa Reports w interfejsie API Campaign Managera 360 umożliwia tworzenie i aktualizowanie raportów z Kreatora raportów za pomocą obiektów zasobów raportów. Zasób raportu zawiera podstawowe informacje o raporcie, który ma zostać wygenerowany, oraz o strukturze danych wyjściowych raportu.

Z tego przewodnika dowiesz się, jak programowo tworzyć i aktualizować raporty z Kreatora raportów za pomocą usługi Reports.

Konfigurowanie zasobu raportu

Pierwszym krokiem w tworzeniu lub aktualizowaniu raportu z Kreatora raportów jest skonfigurowanie obiektu zasobu raportu. Jeśli tworzysz nowy raport, zacznij od pustego zasobu i ustaw niezbędne pola. Jeśli aktualizujesz istniejący raport, masz do wyboru:

  1. Preferowane: wykonanie częściowej aktualizacji. W tym przypadku zaczniesz od pustego zasobu i ustawisz pola, które chcesz zmienić. Częściowa aktualizacja zapisuje tylko zmiany w określonych polach.
  2. Wykonanie pełnej aktualizacji. W tym przypadku wczytasz istniejący zasób raportu i bezpośrednio zmodyfikujesz jego pola. Pełna aktualizacja zawsze zapisuje wszystkie pola raportu.

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

PoleOpis
Pola wymagane
nazwaNazwa raportu.
typTyp raportu.
Pola opcjonalne
dostarczanieUstawienia dostarczania e-maili z raportem.
fileNameNazwa pliku używana podczas generowania plików raportu.
formatFormat wyjściowy raportu – CSV lub Excel.
harmonogramHarmonogram używany do cyklicznego generowania raportu.

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

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

Określanie kryteriów raportu

Gdy wybierzesz typ raportu i skonfigurujesz wspólne pola, następnym krokiem będzie określenie kryteriów raportu. Kryteria raportu służą do ograniczenia zakresu raportu, dzięki czemu zwracane są tylko istotne informacje. Określają też strukturę danych wyjściowych raportu.

Używane kryteria zależą od typu raportu. Zależność między typem raportu a kryteriami jest opisana w tabeli poniżej:

Typ raportu Pole kryteriów
STANDARD kryteria
REACH reachCriteria
PATH_TO_CONVERSION pathToConversionCriteria
FLOODLIGHT floodlightCriteria
CROSS_DIMENSION_REACH crossDimensionReachCriteria

Każdy z tych kryteriów specyficznych dla typu raportu udostępnia nieco inny zestaw pól, ale istnieje też zestaw wspólnych pól kryteriów, które są ogólnie przydatne do kontrolowania danych wyjściowych raportu:

Pole Opis
dateRange Daty, dla których ma zostać wygenerowany ten raport. Można ich użyć do określenia niestandardowej daty rozpoczęcia i zakończenia lub względnego zakresu dat.
dimensionFilters Lista filtrów, które ograniczają zwracane 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 mają zostać uwzględnione w danych wyjściowych raportu.
metricNames Standardowe jednostki miary, które mają zostać uwzględnione w danych wyjściowych raportu.

Więcej informacji o wybieraniu wymiarów, danych i filtrów do raportu znajdziesz w sekcji Określanie zgodności pól. Dodatkowe pola kryteriów specyficzne dla typu raportu są opisane w dokumentacji i Centrum pomocy.

Poniższy przykład dodaje podstawowe kryteria do naszego zasobu raportu standardowego:

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 = datetime.date.today()
start_date = end_date - datetime.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 filtrów zapytań

Podczas konfigurowania filtrów do raportu musisz określić dokładne wartości, których filtry będą używać do ograniczania danych wyjściowych raportu. Jeśli nie masz pewności, jakie są możliwe wartości danego filtra, wyszukaj je za pomocą usługi DimensionValues.

Podstawowe zapytanie o wartości wymiarów zawiera nazwę wymiaru oraz datę rozpoczęcia i datę zakończenia. Daty rozpoczęcia i zakończenia ograniczają odpowiedź do wartości prawidłowych w tym okresie. Dodatkowe filtry można określić, jeśli chcesz dodatkowo ograniczyć wyniki zapytania.

Poniższy przykład wyszukuje prawidłowe wartości filtra reklamodawcy w datach, w których będzie generowany raport, 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ślanie zgodności pól

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

Podczas tworzenia zasobu raportu możesz przekazać go do usługi Reports.compatibleFields, aby sprawdzić, które pola są prawidłowe w przypadku wybranych już pól. Konfiguracja raportu zostanie przeanalizowana i zostanie zwrócona odpowiedź zawierająca zgodne wymiary, dane i filtry. Ponieważ nie wszystkie pola w tej odpowiedzi muszą być ze sobą zgodne, może być konieczne wysłanie kilku żądań, aby upewnić się, że wszystkie wybrane pola będą ze sobą współpracować.

Poniższy przykład pokazuje, jak wysłać przykładowe żądanie zgodnych pól, używając jako danych wejściowych naszego 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

Zapisywanie raportu

Ostatnim krokiem w tym procesie jest zapisanie zasobu raportu. Jeśli tworzysz nowy raport, możesz go wstawić za pomocą wywołania Reports.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=str(profile_id), body=report).execute()
)

Ruby

report = service.insert_report(profile_id, report)

Możesz zapisać zmiany, wywołując Reports.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 w treści odpowiedzi zostanie zwrócona kopia zasobu raportu. Ten zasób będzie zawierał kilka nowych wypełnionych pól, z których najważniejsze jest pole id. Ten identyfikator będzie używany do odwoływania się do tego raportu w pozostałej części procesu.