Créer et mettre à jour des rapports

Le service Rapports de l'API Campaign Manager 360 vous permet de créer et de mettre à jour des rapports de l'outil de création de rapports à l'aide d'objets de ressources de rapports. Une ressource de rapport présente des informations de base sur un rapport à exécuter, ainsi que la structure du rapport généré.

Ce guide explique comment créer et mettre à jour par programmation des rapports de l'outil de création de rapports via le service Reports.

Remarque :La création d'un rapport valide n'est pas une mince affaire. Certains sous-ensembles de dimensions et de métriques ne sont valides que dans des combinaisons spécifiques. Par conséquent, nous vous recommandons de commencer par créer des rapports à l'aide de l'outil de création de rapports, puis de les cloner et de les modifier via l'API.

Configurer une ressource de rapport

La première étape de la création ou de la mise à jour d'un rapport de l'outil de création de rapports consiste à configurer un objet "Ressource de rapport". Si vous créez un rapport, vous commencez avec une ressource vide et vous définissez les champs nécessaires. Si vous mettez à jour un rapport existant, vous avez le choix entre les options suivantes:

1. À privilégier: effectuer une mise à jour partielle. À l'aide de cette approche, vous allez commencer avec une ressource vide et définir les champs à modifier. Une mise à jour partielle n'enregistre que les modifications apportées aux champs que vous spécifiez.
2. Exécution d'une mise à jour complète... Cette méthode vous permet de charger une ressource de rapport existante et de modifier directement ses champs. Une mise à jour complète enregistre toujours tous les champs du rapport.

Le contenu exact d'une ressource de rapport varie en fonction du type de rapport que vous configurez. Malgré cela, quelques champs sont communs à tous les types de rapports:

Champ	Description
Champs obligatoires
nom	Nom du rapport.
type	Type de rapport.
Champs facultatifs
livraison	Paramètres d'envoi du rapport par e-mail.
fileName	Nom de fichier utilisé lors de la génération des fichiers de ce rapport.
format	Format de sortie du rapport (CSV ou Excel).
calendrier	Calendrier permettant de générer un rapport de façon récurrente.

Ces champs communs constituent la base de votre rapport. L'exemple ci-dessous illustre la création d'une ressource de rapport 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'
)

Définir les critères du rapport

Une fois que vous avez choisi un type de rapport et configuré les champs communs, l'étape suivante consiste à définir les critères du rapport. Les critères du rapport sont utilisés pour limiter la portée de votre rapport, en s'assurant que seules les informations pertinentes sont renvoyées. Il définit également la structure des résultats du rapport.

Les critères utilisés dépendent du type de rapport. La relation entre le type de rapport et les critères est expliquée dans le tableau suivant:

Type de rapport	Champ "Critères"
STANDARD	critères
REACH	reachCriteria
PATH_TO_CONVERSION	pathToConversionCriteria
FLOODLIGHT	floodlightCriteria
CROSS_DIMENSION_REACH	crossDimensionReachCriteria

Bien que chacun de ces critères spécifiques au type expose un ensemble de champs légèrement différent, il existe un ensemble de champs de critères communs qui sont généralement utiles pour contrôler la sortie des rapports:

Champ	Description
dateRange	Dates pour lesquelles ce rapport doit être généré. Permet de spécifier des dates de début et de fin personnalisées, ou une plage de dates relative. Remarque:Lorsque vous exécutez des rapports via l'API, les plages de dates relatives telles que YESTERDAY sont résolues dans le fuseau horaire Amérique/Los Angeles. Cela peut entraîner des résultats inattendus pour les utilisateurs se trouvant dans des fuseaux horaires différents.
dimensionFilters	Liste de filtres limitant les résultats renvoyés. Pour en savoir plus sur la configuration des filtres, consultez la section Valeurs des filtres de requête.
dimensions	Liste des éléments Campaign Manager 360 à inclure dans le rapport généré.
metricNames	Unités de mesure standards à inclure dans le rapport généré.

Pour savoir comment choisir des dimensions, des métriques et des filtres pour votre rapport, consultez la section Déterminer la compatibilité des champs. Pour en savoir plus sur les autres champs de critères spécifiques aux types, consultez la documentation de référence et le Centre d'aide.

L'exemple ci-dessous ajoute un critère de base à notre ressource de rapport 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

Valeurs du filtre de requête

Lorsque vous configurez des filtres pour un rapport, vous devez spécifier les valeurs exactes que les filtres utiliseront pour limiter le résultat du rapport. Si vous n'êtes pas sûr des valeurs possibles pour un filtre particulier, recherchez-les à l'aide du service DimensionValues.

Une requête de valeurs de dimension de base contient un nom de dimension, ainsi qu'une date de début et une date de fin. Les dates de début et de fin limitent la réponse aux valeurs valides au cours de cette période. Vous pouvez spécifier des filtres supplémentaires si vous devez limiter davantage les résultats de la requête.

L'exemple ci-dessous recherche des valeurs de filtre d'annonceur valides aux dates de génération de notre rapport et les ajoute aux critères du rapport:

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

Déterminer la compatibilité des champs

Lorsque vous configurez les critères de votre rapport, gardez à l'esprit que toutes les combinaisons de métriques, de dimensions et de filtres ne sont pas valides. Vous ne serez pas autorisé à enregistrer un rapport contenant une combinaison non valide. Il est donc important de vérifier que les champs que vous prévoyez d'utiliser sont compatibles entre eux.

Lorsque vous créez votre ressource de rapport, vous pouvez la transmettre au service Reports.compatibleFields pour voir quels champs sont valides en fonction de ceux que vous avez déjà sélectionnés. La configuration du rapport est analysée, et une réponse contenant les dimensions, métriques et filtres compatibles s'affiche. Comme il n'est pas garanti que les champs de cette réponse soient tous compatibles les uns avec les autres, vous devrez peut-être effectuer plusieurs requêtes pour vous assurer que tous les champs sélectionnés fonctionneront ensemble.

L'exemple ci-dessous montre comment effectuer une requête de champs compatibles en utilisant notre ressource de rapport comme entrée:

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

Enregistrer le rapport

La dernière étape de ce processus consiste à enregistrer votre ressource de rapport. Si vous créez un rapport, vous pouvez l'insérer avec un appel à 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)

Si vous effectuez une mise à jour partielle, vous pouvez enregistrer vos modifications en appelant 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)

Si vous avez décidé d'effectuer une mise à jour complète, vous pouvez enregistrer vos modifications en appelant 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);

Après une demande d'enregistrement réussie, une copie de la ressource de rapport est renvoyée dans le corps de la réponse. Dans cette ressource, quelques nouveaux champs seront remplis, le plus important étant le champ "id". Il s'agit de l'ID que vous utiliserez pour vous référer au rapport tout au long du reste de votre workflow.