Crea e aggiorna report

Il servizio di report per l'API Campaign Manager 360 consente di creare e aggiornare i report di Report Builder utilizzando gli oggetti delle risorse di report. Una risorsa del report definisce le informazioni di base su un report da eseguire e 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: creare un report valido non è un compito banale. Alcuni sottoinsiemi di dimensioni e metriche sono validi solo in combinazioni specifiche. Ti consigliamo quindi di creare inizialmente i report con Report Builder per poi clonarli e modificarli tramite l'API.

Configurare una risorsa del report

Il primo passo per creare o aggiornare un report di Report Builder è configurare un oggetto risorsa del report. Se vuoi creare un nuovo report, devi iniziare con una risorsa vuota e impostare i campi necessari. Se vuoi aggiornare un report esistente, puoi scegliere tra:

1. Preferito: eseguire un aggiornamento parziale. Con questo approccio, devi iniziare con una risorsa vuota e impostare i campi da modificare. Un aggiornamento parziale salva solo le modifiche ai campi specificati.
2. Aggiornamento completo. Utilizzando questo approccio, caricherai una risorsa di report esistente e modificherai direttamente i relativi campi. Un aggiornamento completo salva sempre tutti i campi del report.

I contenuti esatti di una risorsa del 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
name	Il nome del report.
digita	Il tipo di report.
Campi facoltativi
distribuzione	Le impostazioni di invio delle email del report.
Nome file	Il nome file utilizzato per generare i file del report.
dell'annuncio	Il formato di output del report, CSV o Excel.
pianificazione	Una pianificazione utilizzata per eseguire il report su base ricorrente.

Questi campi comuni costituiscono lo scheletro del report. L'esempio riportato di seguito illustra la creazione di una nuova risorsa del 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'
)

Definire i criteri del report

Dopo aver scelto un tipo di report e configurato i campi comuni, il passaggio successivo consiste nella definizione dei criteri del report. I criteri del report vengono utilizzati per limitare l'ambito del report e garantire che vengano restituite solo informazioni pertinenti. Definisce inoltre 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 dei criteri
STANDARD	criteri
REACH	copertura criteri
PATH_TO_CONVERSION	Percorsi verso la conversione
LUCE FLOOD	inondazione
RAGGIUNTO_DIMENSIONE_CROSS	crossDimensionReachCriteria

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

Campo	Descrizione
dataintervallo	Le date per le quali questo report deve essere eseguito. Può essere utilizzato per specificare una data di inizio e una di fine personalizzate oppure un intervallo di date relativo. Nota: quando esegui i 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.
filtri dimensioni	Un elenco di filtri che limitano i risultati restituiti. Per ulteriori informazioni sulla configurazione dei filtri, consulta la sezione sui valori dei filtri di query.
dimensioni	Un elenco di elementi di Campaign Manager 360 da includere nell'output del report.
metricheName	Unità di misura standard da includere nell'output del report.

Per ulteriori informazioni sulla scelta delle dimensioni, delle metriche e dei filtri per il report, consulta la sezione sulla determinazione della compatibilità dei campi. Ulteriori campi dei criteri specifici per tipo sono descritti nella documentazione di riferimento e nel Centro assistenza.

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

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

L'esempio riportato di seguito cerca i valori del filtro inserzionista validi nelle 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

Determina 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 è consentito salvare un report contenente una combinazione non valida, pertanto è importante che i campi utilizzati siano compatibili tra loro.

Durante la creazione della risorsa del report, puoi trasmetterla al servizio reports.compatibleFields per vedere quali sono validi dato 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 tutti i campi di questa risposta sono compatibili tra loro, potrebbe essere necessario effettuare più richieste per garantire che tutti i campi scelti funzionino insieme.

L'esempio riportato di seguito illustra come effettuare una richiesta di campi compatibili di esempio utilizzando la risorsa del 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 questo processo è salvare la risorsa del report. Se stai creando un nuovo report, puoi inserirlo con una chiamata a Report.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 devi eseguire un aggiornamento parziale, puoi salvare le modifiche chiamando Report.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 Report.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, verrà restituita una copia della risorsa del report nel corpo della risposta. In questa risorsa verranno compilati alcuni nuovi campi, il più importante è il campo ID. Questo ID è quello che utilizzerai per fare riferimento a questo report durante il resto del flusso di lavoro.