Creare e aggiornare i report

Il servizio di report per l'API Campaign Manager 360 consente di creare e aggiornare i report di Report Builder utilizzando oggetti di risorse dei report. Una risorsa report descrive le informazioni di base su un report da eseguire, nonché la struttura dell'output del report.

Questa guida illustra nei dettagli come creare e aggiornare in modo programmatico i report di Report Builder tramite il servizio Report.

Nota: la creazione di un report valido non è un'attività di poco conto. Alcuni sottoinsiemi di dimensioni e metriche sono validi solo in combinazioni specifiche. Per questo motivo, ti consigliamo di creare inizialmente report con Report Builder e poi di clonarli e modificarli tramite l'API.

Configurare una risorsa report

Il primo passaggio per la creazione o l'aggiornamento di un report di Report Builder consiste nel configurare un oggetto risorsa del report. Se crei un nuovo report, inizierai con una risorsa vuota e imposterai i campi necessari. Se stai aggiornando un report esistente, puoi scegliere tra:

1. Preferito: viene eseguito un aggiornamento parziale. Con questo approccio, inizierai con una risorsa vuota e imposterai i campi da modificare. Un aggiornamento parziale salva solo le modifiche ai campi specificati.
2. È in corso l'esecuzione di un aggiornamento completo. Con questo approccio, caricherai una risorsa report esistente e ne modificherai direttamente i campi. Un aggiornamento completo salva sempre tutti i campi del report.

I contenuti esatti di una risorsa report variano a seconda del tipo di report che stai configurando. In ogni caso, esistono alcuni campi comuni a tutti i tipi di report:

Campo	Descrizione
Campi obbligatori
nome	Il nome del report.
tipo	Il tipo di report.
Campi facoltativi
consegna a domicilio	Le impostazioni di recapito delle email del report.
fileName	Il nome file utilizzato durante la generazione di file di report per questo report.
dell'annuncio	Il formato di output del report, CSV o Excel.
programmazione	Una pianificazione utilizzata per eseguire il report su base ricorrente.

Questi campi comuni costituiscono lo schema del report. L'esempio seguente illustra la creazione di una nuova risorsa di report standard:

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

Definisci i criteri del report

Dopo aver scelto un tipo di report e configurato i campi comuni, devi definire i criteri del report. I criteri del report vengono utilizzati per limitare l'ambito del report e garantire che vengano restituite solo le informazioni pertinenti. oltre a definire la struttura dell'output del report.

I criteri utilizzati dipendono dal tipo di report. La relazione tra tipo di report e criteri è spiegata nella seguente tabella:

Tipo di rapporto	Campo Criteri
STANDARD	criteri
REACH	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
FLOODLIGHT	floodlightCriteria
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

Sebbene ognuno di questi criteri specifici del tipo esponi un insieme leggermente diverso di campi, esiste una serie di campi con criteri comuni generalmente utili per controllare l'output del report:

Campo	Descrizione
dateRange	Le date durante le quali deve essere eseguito il report. Può essere utilizzato per specificare una data di inizio e di fine personalizzata o un intervallo di date relativo. Nota: quando esegui report tramite l'API, gli intervalli di date relativi, ad esempio YESTERDAY, vengono risolti nel fuso orario di America/Los Angeles. Ciò potrebbe causare risultati imprevisti per gli utenti di fusi orari diversi.
dimensionFilters	Un elenco di filtri che limitano i risultati restituiti. Per ulteriori informazioni sulla configurazione dei filtri, consulta la sezione Valori del filtro di query.
dimensioni	Un elenco di elementi di Campaign Manager 360 da includere nell'output del report.
metricNames	Unità di misura standard da includere nell'output del report.

Per saperne di più sulla scelta delle dimensioni, delle metriche e dei filtri per il report, consulta la sezione su come determinare la compatibilità dei campi. Ulteriori campi relativi ai criteri specifici del tipo sono descritti nella documentazione di riferimento e nel Centro assistenza.

L'esempio riportato di seguito consente di aggiungere un criterio di base alla risorsa dei report standard:

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

Valori del filtro di query

Quando configuri i filtri per un report, devi specificare i valori esatti che i filtri utilizzeranno per limitare l'output del report. Se non sapete quali sono i valori possibili per un determinato filtro, cercateli utilizzando il servizio DimensionValues.

Una query sui valori delle dimensioni di base contiene un nome dimensione, nonché una data di inizio e una data di fine. Le date di inizio e di fine limitano la risposta ai valori validi in quel periodo di tempo. Se devi limitare ulteriormente i risultati della query, puoi specificare filtri aggiuntivi.

L'esempio riportato di seguito cerca valori di filtro inserzionista validi durante le date di esecuzione del report e li aggiunge ai criteri del report:

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

Determinare la compatibilità dei campi

Quando configuri i criteri del report, è importante ricordare che non tutte le combinazioni di metriche, dimensioni e filtri sono valide. Non puoi salvare un report contenente una combinazione non valida, pertanto è importante verificare che i campi che prevedi di utilizzare siano compatibili tra loro.

Durante la creazione della risorsa report, puoi passarla al servizio Reports.compatibleFields per vedere quali campi sono validi in base a quelli già selezionati. La configurazione del report verrà analizzata e verrà restituita una risposta contenente le dimensioni, le metriche e i filtri compatibili. Poiché non è garantito che tutti i campi di questa risposta siano compatibili tra loro, potrebbe essere necessario effettuare più richieste per garantire che tutti i campi scelti funzionino insieme.

L'esempio seguente illustra come effettuare una richiesta di campi compatibili di esempio, utilizzando la nostra risorsa report come input:

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

Salva il report

Il passaggio finale di questa procedura consiste nel salvare la risorsa del report. Se crei un nuovo report, puoi inserirlo con una chiamata a 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)

Se esegui un aggiornamento parziale, puoi salvare le modifiche richiamando 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)

In alternativa, se hai deciso di eseguire un aggiornamento completo, puoi salvare le modifiche chiamando 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);

Dopo una richiesta di salvataggio riuscita, nel corpo della risposta verrà restituita una copia della risorsa del report. Questa risorsa avrà alcuni nuovi campi compilati, il più importante dei quali è il campo ID. Questo ID è lo strumento che utilizzerai per fare riferimento al report nel resto del flusso di lavoro.