Créer et mettre à jour des rapports

Le service Reports 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 rapport. Une ressource de rapport décrit les informations de base sur un rapport à exécuter, ainsi que la structure de la sortie du rapport.

Ce guide explique comment créer et mettre à jour des rapports du générateur de rapports de manière programmatique à l'aide du service Reports.

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

Configurer une ressource de rapport

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

1. Recommandé : effectuez une 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 que vous spécifiez.
2. Effectuer une mise à jour complète. Cette approche 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. Toutefois, certains 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 par e-mail du rapport.
fileName	Nom de fichier utilisé lors de la génération des fichiers de rapport pour ce rapport.
format	Format de sortie du rapport (CSV ou Excel).
calendrier	Planning utilisé pour exécuter votre rapport de manière récurrente.

Ces champs communs constituent la structure 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 de rapport permettent de limiter le champ d'application de votre rapport et de s'assurer que seules les informations pertinentes sont renvoyées. Il définit également la structure du résultat du rapport.

Les critères utilisés dépendent du type de rapport. Le tableau suivant explique la relation entre le type de rapport et les critères :

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 à un 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 exécuté. Permet de spécifier une date 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 America/Los_Angeles. Cela peut entraîner des résultats inattendus pour les utilisateurs situés dans différents fuseaux horaires.
dimensionFilters	Liste de filtres qui limitent les résultats renvoyés. Pour savoir comment configurer des filtres, consultez la section Valeurs de filtre de requête.
Dimensions	Liste des éléments Campaign Manager 360 à inclure dans le rapport.
metricNames	Unités de mesure standards à inclure dans le rapport.

Pour en savoir plus sur le choix des dimensions, des métriques et des filtres pour votre rapport, consultez la section sur la détermination de la compatibilité des champs. Vous trouverez des informations sur les champs de critères supplémentaires spécifiques à chaque type dans 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 de 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 les résultats du rapport. Si vous ne savez pas quelles sont les valeurs possibles pour un filtre spécifique, 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 au cours de cette période. Vous pouvez spécifier des filtres supplémentaires si vous avez besoin de limiter davantage les résultats de la requête.

L'exemple ci-dessous recherche les valeurs de filtre d'annonceur valides pour les dates d'exécution du 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, il est important de vous rappeler que toutes les combinaisons de métriques, de dimensions et de filtres ne sont pas valides. Vous ne pourrez pas 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 pour 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 tous garantis d'être compatibles les uns avec les autres, vous devrez peut-être effectuer plusieurs demandes pour vous assurer que tous les champs que vous choisissez fonctionneront ensemble.

L'exemple ci-dessous montre comment effectuer une demande de champs compatibles à l'aide de 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 la ressource de votre rapport. Si vous créez un rapport, vous pouvez l'insérer en appelant 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);

Une fois la demande d'enregistrement traitée, une copie de la ressource du rapport est renvoyée dans le corps de la réponse. Cette ressource comportera quelques nouveaux champs, dont le plus important est le champ "id". Cet ID vous permettra de faire référence à ce rapport dans le reste de votre workflow.