Interfejs Campaign Manager 360 API w wersji 4 jest wycofany i zostanie zamknięty 26 lutego 2026 r. Aby uniknąć przerw w działaniu usługi, do tego czasu przejdź na wersję 5.

Tworzenie i aktualizowanie raportów

Usługa Raporty interfejsu Campaign Manager 360 API umożliwia tworzenie i aktualizowanie raportów Kreatora raportów za pomocą obiektów zasobów raportu. Zasób raportu zawiera podstawowe informacje o raporcie, który ma zostać uruchomiony, a także strukturę danych wyjściowych raportu.

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

Konfigurowanie zasobu raportu

Pierwszym krokiem w tworzeniu lub aktualizowaniu raportu w Kreatorze raportów jest skonfigurowanie obiektu zasobu raportu. Jeśli tworzysz nowy raport, zaczniesz od pustego zasobu i ustawisz niezbędne pola. Jeśli aktualizujesz istniejący raport, możesz:

Preferowane: wykonanie aktualizacji częściowej. W tym przypadku zaczynasz od pustego zasobu i ustawiasz pola, które chcesz zmienić. Aktualizacja częściowa zapisuje tylko zmiany w określonych polach.
Przeprowadzanie pełnej aktualizacji. 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 typu konfigurowanego raportu. Niemniej jednak istnieją pola 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 wspólne pola stanowią szkielet raportu. Przykład poniżej pokazuje tworzenie 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'
)

Określanie kryteriów raportu

Po wybraniu typu raportu i skonfigurowaniu wspólnych pól następnym krokiem jest zdefiniowanie kryteriów raportu. Kryteria raportu służą do ograniczenia jego zakresu, dzięki czemu zwracane są tylko istotne informacje. Określa też strukturę danych wyjściowych raportu.

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

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

Chociaż każde z tych kryteriów specyficznych dla typu udostępnia nieco inny zestaw pól, istnieje 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że służyć do określania niestandardowej daty rozpoczęcia i zakończenia lub względnego zakresu dat. Uwaga: podczas generowania raportów za pomocą interfejsu API względne zakresy dat, np. `YESTERDAY`, są rozwiązywane w strefie czasowej America/Los Angeles. Może to powodować nieoczekiwane wyniki dla 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 filtrów zapytań.
wymiary	Lista elementów Campaign Managera 360, które mają być uwzględnione w raporcie.
metricNames	Standardowe jednostki miary, które mają być uwzględnione w raporcie.

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 danego typu są wyjaśnione w dokumentacji i Centrum pomocy.

W przykładzie poniżej do standardowego zasobu raportu dodajemy podstawowe kryteria:

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 zapytania

Podczas konfigurowania filtrów 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, sprawdź je za pomocą usługi DimensionValues.

Podstawowe zapytanie o 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 ważnych w tym okresie. Jeśli chcesz jeszcze bardziej ograniczyć wyniki zapytania, możesz określić dodatkowe filtry.

Poniższy przykład wyszukuje prawidłowe wartości filtra reklamodawcy w okresie, w którym 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 możesz zapisać raportu, który zawiera nieprawidłową kombinację, dlatego ważne jest, aby pola, których chcesz użyć, były 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 zwrócona zostanie odpowiedź zawierająca zgodne wymiary, dane i filtry. Nie wszystkie pola w tej odpowiedzi muszą być ze sobą zgodne, więc może być konieczne wysłanie kilku żądań, aby mieć pewność, że wszystkie wybrane pola będą ze sobą współpracować.

Przykład poniżej pokazuje, jak wysłać przykładowe żądanie dotyczące 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

Zapisz raport

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=profile_id, body=report).execute()

Ruby

report = service.insert_report(profile_id, report)

Jeśli wykonujesz częściową aktualizację, możesz zapisać zmiany, wywołując funkcję 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 zapisaniu żądania w treści odpowiedzi zostanie zwrócona kopia zasobu raportu. Ten zasób będzie zawierać kilka nowych 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 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

Określanie kryteriów raportu

C#

Java

PHP

Python

Ruby

Wartości filtra zapytania

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