Creare e aggiornare i report

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

Questa guida descrive in dettaglio 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à banale. Alcuni sottoinsiemi di dimensioni e metriche sono validi solo in combinazioni specifiche. Pertanto, ti consigliamo di creare inizialmente i report con Report Builder e poi di clonarli e modificarli tramite l'API.

Configurare una risorsa report

Il primo passaggio per creare o aggiornare un report di Report Builder consiste nel configurare un oggetto risorsa report. Se stai creando un nuovo report, inizierai con una risorsa vuota e imposterai i campi necessari. Se stai aggiornando un report esistente, puoi scegliere tra:

1. Preferito: esecuzione di un aggiornamento parziale. Con questo approccio, inizierai con una risorsa vuota e imposterai i campi che vuoi modificare. Un aggiornamento parziale salva solo le modifiche ai campi specificati.
2. Esecuzione di un aggiornamento completo. Con questo approccio, caricherai una risorsa report esistente e modificherai direttamente i relativi 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. Tuttavia, 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 invio via email del report.
fileName	Il nome file utilizzato durante la generazione dei 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 la struttura del report. L'esempio seguente illustra la creazione di una nuova risorsa 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, il passaggio successivo consiste nel definire i criteri del report. I criteri del report vengono utilizzati per limitare l'ambito del report, garantendo che vengano restituite solo le informazioni pertinenti. Definisce anche la struttura dell'output del report.

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

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

Sebbene ciascuno di questi criteri specifici per tipo esponga un insieme leggermente diverso di campi, esiste un insieme di campi dei criteri comuni che sono generalmente utili per controllare l'output del report:

Campo	Descrizione
dateRange	Le date per cui deve essere eseguito questo report. Può essere utilizzato per specificare una data di inizio e di fine personalizzata o un intervallo di date relativo. Nota:quando generi report tramite l'API, gli intervalli di date relativi come YESTERDAY vengono risolti nel fuso orario America/Los Angeles. Ciò potrebbe causare risultati imprevisti per gli utenti in fusi orari diversi.
dimensionFilters	Un elenco di filtri che limitano i risultati restituiti. Per saperne di più sulla configurazione dei filtri, consulta la sezione Valori dei filtri delle 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 di dimensioni, metriche e filtri per il report, consulta la sezione relativa alla determinazione della compatibilità dei campi. Ulteriori campi di criteri specifici per il tipo sono illustrati nella documentazione di riferimento e nel Centro assistenza.

L'esempio riportato di seguito aggiunge un criterio di base alla risorsa 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 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 sai quali sono i valori possibili per un determinato filtro, cercali utilizzando il servizio DimensionValues.

Una query di base sui valori delle dimensioni contiene un nome della 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 i valori di filtro dell'inserzionista validi durante le date in cui verrà eseguito il 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 ti sarà consentito salvare un report che contiene una combinazione non valida, quindi è importante assicurarsi che i campi che intendi utilizzare siano compatibili tra loro.

Mentre crei la risorsa report, puoi passarla al servizio Reports.compatibleFields per vedere quali campi sono validi in base a quelli che hai già selezionato. La configurazione del report verrà analizzata e verrà restituita una risposta contenente le dimensioni, le metriche e i filtri compatibili. Poiché non è garantita la compatibilità di tutti i campi di questa risposta, potresti dover effettuare più richieste per assicurarti che tutti i campi che scegli funzionino insieme.

L'esempio seguente mostra 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 stai creando 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 chiamando 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)

Se invece 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 report. Questa risorsa avrà alcuni nuovi campi compilati, il più importante dei quali è il campo id. Questo ID verrà utilizzato per fare riferimento a questo report nel resto del flusso di lavoro.