Ta strona została przetłumaczona przez Cloud Translation API.

Tworzenie i aktualizowanie raportów

W przypadku interfejsu API Campaign Managera 360 usługa Raporty umożliwia tworzenie i aktualizowanie raportów w Kreatorze raportów za pomocą obiektów zasobów raportów. Zasób raportu zawiera podstawowe informacje o raporcie do wygenerowania oraz strukturę jego wyników.

Z tego przewodnika dowiesz się, jak automatycznie tworzyć i aktualizować raporty Kreatora raportów w usłudze Raporty.

Konfigurowanie zasobu raportu

Pierwszym krokiem podczas tworzenia lub aktualizowania raportu w Kreatorze raportów jest skonfigurowanie obiektu jego zasobu. Jeśli tworzysz nowy raport, zaczniesz od pustego zasobu i ustawisz niezbędne pola. Jeśli aktualizujesz istniejący raport, masz do wyboru te opcje:

Preferowana: przeprowadza częściową aktualizację. W ten sposób rozpoczniesz od pustego zasobu i ustawisz pola, które chcesz zmienić. Częściowa aktualizacja zapisuje zmiany tylko w wybranych polach.
Wykonuję pełną aktualizację. W ten sposób 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 konfigurowanego typu raportu. Jest jednak kilka pól, które są wspólne dla wszystkich typów raportów:

Pole	Opis
Pola wymagane
nazwa	Nazwa raportu.
typ	Typ raportu.
Pola opcjonalne
dostarczanie	Ustawienia dostarczania raportu e-mailem.
fileName	Nazwa pliku używana podczas generowania plików raportu dla tego raportu.
reklamy	Format wyjściowy raportu: CSV lub Excel.
harmonogram	Harmonogram używany do cyklicznego generowania raportu.

Te typowe pola składają się na szkielet raportu. Poniższy przykład pokazuje proces tworzenia nowego zasobu 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'
)

Definiowanie kryteriów raportu

Po wybraniu typu raportu i skonfigurowaniu wspólnych pól kolejnym krokiem jest określenie kryteriów raportu. Kryteria raportu służą do ograniczania jego zakresu, tak aby zawierały tylko istotne informacje. Definiuje również strukturę wyników raportu.

Ich kryteria zależą od typu raportu. Zależność między typem a kryteriami raportu została objaśniona w tej tabeli:

Typ raportu	Pole kryteriów
STANDARDOWA	kryterium
REACH	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
FLOODLIGHT	floodlightCriteria
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

Chociaż każde z tych kryteriów specyficznych dla danego typu ujawnia nieco inny zestaw pól, istnieje zestaw wspólnych pól kryteriów, które ogólnie przydają się do kontrolowania wyników raportu:

Pole	Opis
dateRange	Daty, dla których chcesz wygenerować raport. Pozwala 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ą stosowane w strefie czasowej America/Los Angeles. Może to powodować nieoczekiwane rezultaty u użytkowników w różnych strefach czasowych.
dimensionFilters	Lista filtrów, które ograniczają zwracane wyniki. Więcej informacji o konfigurowaniu filtrów znajdziesz w sekcji Wartości filtra zapytań.
wymiary	Lista elementów Campaign Managera 360, które mają być uwzględnione w raporcie.
metricNames	Standardowe jednostki miary do uwzględnienia w wynikach raportu.

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

Poniższy przykład pokazuje, jak dodać podstawowe kryteria do 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 = 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

Zapytanie o wartości filtrów

Konfigurując filtry raportu, musisz dokładnie określić wartości, których filtry będą używać do ograniczania wyników raportu. Jeśli nie masz pewności, jakie są możliwe wartości danego filtra, wyszukaj je za pomocą usługi DimensionValues.

Zapytanie o podstawowe wartości wymiaru 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. Jeśli chcesz jeszcze bardziej ograniczyć wyniki zapytania, możesz określić dodatkowe filtry.

Przykład poniżej pozwala wyszukać prawidłowe wartości filtra reklamodawców w okresach, w których będzie generowany raport, i dodać 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 można zapisać raportu zawierającego nieprawidłową kombinację, dlatego należy zadbać o to, by pola, których chcesz użyć, są ze sobą zgodne.

Podczas tworzenia zasobu raportu możesz go przekazać do usługi Reports.compatibleFields, aby sprawdzić, które pola są prawidłowe, biorąc pod uwagę wybrane już pola. Konfiguracja raportu zostanie przeanalizowana, a odpowiedź zawierająca zgodne wymiary, dane i filtry zostanie zwrócona. Nie możemy zagwarantować, że wszystkie pola w tej odpowiedzi będą ze sobą zgodne, dlatego konieczne może być przesłanie wielu żądań, aby wszystkie wybrane pola ze sobą działały.

Poniższy przykład pokazuje, jak utworzyć przykładowe żądanie zgodnych pól z wykorzystaniem naszego zasobu raportu jako danych wejściowych:

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

Ruby

report = service.insert_report(profile_id, report)

Jeśli przeprowadzasz częściową aktualizację, możesz zapisać zmiany, używając wywołania 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 funkcję 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 żądaniu zapisu kopia zasobu raportu zostanie zwrócona w treści odpowiedzi. Ten zasób będzie miał wypełniony kilka nowych pól, z których najważniejszym jest pole identyfikatora. Za pomocą tego identyfikatora będziesz się odwoływać do raportu w pozostałej części przepływu pracy.

Tworzenie i aktualizowanie raportów Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Konfigurowanie zasobu raportu

C#

Java

PHP

Python

Ruby

Definiowanie kryteriów raportu

C#

Java

PHP

Python

Ruby

Zapytanie o wartości filtrów

C#

Java

PHP

Python

Ruby

Określanie zgodności pól

C#

Java

PHP

Python

Ruby

Zapisz raport

C#

Java

PHP

Python

Ruby

C#

Java

PHP

Python

Ruby

C#

Java

PHP

Python

Ruby

Tworzenie i aktualizowanie raportów