Créer et mettre à jour des rapports

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

Ce guide explique comment créer et mettre à jour des rapports via l'outil de création de rapports de façon automatisée via le service Reports.

Remarque :Créer un rapport valide n'est pas une tâche facile. Certains sous-ensembles de dimensions et de métriques ne sont valides que dans des combinaisons spécifiques. Nous vous recommandons donc de commencer par créer des rapports avec l'outil de création de rapports, puis de les cloner et de les modifier via l'API.

Configurer une ressource de rapport

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

1. À privilégier: mise à jour partielle Avec cette approche, vous commencerez avec une ressource vide et définirez les champs que vous souhaitez modifier. Une mise à jour partielle n'enregistre que les modifications apportées aux champs spécifiés.
2. Mise à jour complète... Avec cette approche, vous allez charger une ressource de rapport existante et 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. Néanmoins, certains champs sont communs à tous les types de rapports:

Champ	Description
Champs obligatoires
name (nom)	Nom du rapport.
type	Type de rapport.
Champs facultatifs
livraison	Paramètres de distribution du rapport par e-mail.
Nom du fichier	Nom de fichier utilisé lors de la génération des fichiers de ce rapport.
format	Format de sortie du rapport (CSV ou Excel).
programmation	Calendrier utilisé pour exécuter votre rapport de façon récurrente.

Ces champs courants 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 d'un rapport

Une fois que vous avez choisi un type de rapport et configuré les champs courants, l'étape suivante consiste à définir les critères du rapport. Les critères servent à limiter la portée de votre rapport en garantissant que seules les informations pertinentes sont renvoyées. Il définit également la structure de sortie du rapport.

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

Type de rapport	Champ "Critères"
STANDARD	critères
REACH	Critères de couverture
PATH_TO_CONVERSION	CheminDeConversion
FROODLIGHT	floodlight
CROSS_DIMENSION_REACH	CrossDimensionReachCriteria

Chacun de ces critères spécifiques à chaque type expose un ensemble de champs légèrement différent, mais un ensemble de champs de critères communs est généralement utile pour contrôler la sortie du rapport:

Champ	Description
dateRange	Dates pour lesquelles ce rapport doit être généré. Vous pouvez spécifier une date de début et une date de fin personnalisées, ou une plage de dates relative. Remarque:Lorsque vous générez des rapports via l'API, les plages de dates relatives comme YESTERDAY sont résolues dans le fuseau horaire Amérique/Los Angeles. Cela peut entraîner des résultats inattendus pour les utilisateurs situés dans des fuseaux horaires différents.
dimensionsFilters	Liste de filtres qui limitent les résultats renvoyés. Pour en savoir plus sur la configuration des filtres, consultez la section Valeurs des filtres de requêtes.
dimensions	Liste des éléments Campaign Manager 360 à inclure dans le rapport généré.
Noms des métriques	Unités de mesure standards à inclure dans le résultat du rapport.

Pour en savoir plus sur le choix des dimensions, des métriques et des filtres de votre rapport, consultez la section sur la détermination des compatibilités des champs. Les champs supplémentaires des critères de type sont expliqués dans la documentation de référence et dans 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 des filtres de requête

Lorsque vous configurez des filtres pour un rapport, vous devez spécifier les valeurs exactes qu'ils utiliseront pour restreindre la sortie du rapport. Si vous n'êtes pas sûr des valeurs possibles pour un filtre donné, recherchez-les à l'aide du service DimensionValues.

Une requête de base sur les valeurs de dimension 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 pendant cette période. Vous pouvez spécifier des filtres supplémentaires pour limiter davantage les résultats de la requête.

L'exemple ci-dessous recherche les valeurs de filtre d'annonceur valides pour les dates de génération de notre rapport et les ajoute aux critères de 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 vos critères, n'oubliez pas que les combinaisons de métriques, dimensions et filtres ne sont pas toutes valides. Vous ne serez pas autorisé à enregistrer un rapport contenant une combinaison non valide. Il est donc important de vous assurer 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 afin de voir quels champs sont valides en fonction de ceux que vous avez déjà sélectionnés. La configuration du rapport sera analysée, et une réponse contenant les dimensions, métriques et filtres compatibles sera renvoyée. Étant donné que les champs de cette réponse ne sont pas forcément compatibles, vous devrez peut-être envoyer plusieurs requêtes pour vous assurer que tous les champs que vous choisissez fonctionnent ensemble.

L'exemple ci-dessous montre comment envoyer un exemple de requête de champs compatibles en utilisant la 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 la méthode 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. Cette ressource comportera de nouveaux champs, le plus important étant le champ "id". Cet ID vous permettra de vous référer au rapport tout au long du workflow.