Demander et télécharger un rapport
La création de rapports est un processus asynchrone. Voici le flux général pour demander un rapport.
- Créer une requête avec les paramètres de rapport
- Envoyer une requête au service de création de rapports
- Le service met la demande en file d’attente jusqu’à ce qu’il soit en mesure de la traiter
- Interroger régulièrement le service pour obtenir la status du travail de rapport
- Lorsque l’status est Réussite, utilisez l’URL que le service fournit pour télécharger le rapport.
Si vous utilisez un langage .NET, Java ou Python, vous devez utiliser les bibliothèques clientes d’API Bing Ads. Les SDK .NET, Java et Python abstractionnt des détails de bas niveau décrits ci-dessous. Par exemple, au lieu d’appeler SubmitGenerateReportRequest et PollGenerateReportRequest pour télécharger un rapport, vous pouvez utiliser une méthode avec le Service Manager Reporting.
Pour obtenir des exemples de code qui montrent comment télécharger des rapports, consultez Exemple de code de demandes de rapport.
Demander un rapport
Déterminez le rapport que vous souhaitez demander. Pour obtenir la liste des rapports que vous pouvez demander, consultez Types de rapports.
Créez un instance de l’objet de demande de rapport. Certains éléments de la demande de rapport sont obligatoires et d’autres sont facultatifs. Définissez les éléments comme il convient pour votre application. Les éléments de la demande de rapport déterminent, entre autres, l’étendue des données à inclure dans le rapport, les colonnes de données à inclure dans le rapport et s’il faut générer le rapport uniquement si toutes les données sont disponibles.
Remarque
Vous devez créer un instance de l’un des objets qui dérive de l’objet de données ReportRequest ; si vous essayez de transmettre l’objet ReportRequest à l’opération SubmitGenerateReport, l’appel échoue.
Créez un instance de l’objet SubmitGenerateReportRequest et définissez l’élément ReportRequest sur la demande de rapport que vous avez sélectionnée à l’étape précédente.
Appelez l’opération SubmitGenerateReport pour envoyer la demande. L’opération est une opération asynchrone qui retourne avant la création du rapport. L’opération retourne un ReportRequestId que vous utilisez dans les étapes suivantes pour déterminer quand le rapport se termine. L’identificateur de la demande de rapport est valide pendant deux jours. Si vous ne téléchargez pas le rapport dans les deux jours, vous devez demander à nouveau le rapport.
Créez une instance de l’objet PollGenerateReportRequest et définissez l’identificateur de demande de rapport sur l’identificateur retourné à l’étape précédente.
Remarque
Vous devez utiliser les mêmes informations d’identification utilisateur pour les opérations SubmitGenerateReport et PollGenerateReport .
Appelez l’opération PollGenerateReport dans une boucle pendant que le status est En attente. L’opération définit l’status sur Réussite lorsque la demande se termine correctement ; un status autre que En attente ou Réussite indique que le rapport a échoué.
La durée d’exécution d’une demande de rapport dépend d’un certain nombre de variables, telles que le type de rapport que vous avez demandé . les valeurs d’agrégation, d’étendue et de période que vous avez spécifiées ; le nombre de lignes attendues ; et le nombre de demandes déjà dans la file d’attente. En raison de ces variables, il est difficile de déterminer un intervalle d’interrogation approprié pour tous les cas. Étant donné que la plupart des rapports doivent se terminer en quelques minutes, l’interrogation à des intervalles de deux à 15 minutes doit être appropriée dans la plupart des cas. Si la période d’interrogation globale dépasse 60 minutes, envisagez d’enregistrer l’identificateur de rapport, de quitter la boucle et de réessayer ultérieurement.
Si la demande se termine correctement, utilisez l’URL dans l’élément ReportDownloadUrl pour télécharger le fichier qui contient le rapport. Après avoir obtenu l’URL de téléchargement, vous avez cinq minutes pour télécharger le rapport. Si vous ne téléchargez pas le rapport dans les cinq minutes suivant l’obtention de l’URL, vous devez interroger pour obtenir une nouvelle URL à utiliser pour télécharger le rapport.
Le fichier de rapport est compressé ; Par conséquent, vous devez le décompresser pour lire le rapport.
Créer une plage de dates personnalisée
La procédure suivante montre comment spécifier une plage de dates personnalisée pour une demande de rapport. Cette option est facultative pour le flux de travail de demande de rapport décrit ci-dessus. Si vous spécifiez une plage de dates personnalisée, vous ne devez pas définir l’élément ReportTime.Prédéfini . Notez également que l’élément Aggregation de l’objet de demande de rapport détermine la façon dont les données pour la période spécifiée sont agrégées.
Créez un instance de l’objet ReportTime. Affectez l’objet ReportTime à l’élément Time de l’objet de données ReportRequest .
Créez un objet Date qui spécifie la date de début de la plage de dates personnalisée. Affectez l’objet Date à l’élément ReportTime.CustomDateRangeStart .
Créez un autre objet Date qui spécifie la date de fin de la plage de dates personnalisée. Affectez l’objet Date à l’élément ReportTime.CustomDateRangeEnd .
L’extrait de code suivant montre comment initialiser un objet de demande de rapport pour demander une plage de dates personnalisée.
// Create an instance of the ReportTime class to hold the report date
// information.
request.Time = new ReportTime();
// Set the start date for the report to one month before today.
DateTime startDate = DateTime.Today.AddMonths(-1);
request.Time.CustomDateRangeStart = new Date();
request.Time.CustomDateRangeStart.Day = startDate.Day;
request.Time.CustomDateRangeStart.Month = startDate.Month;
request.Time.CustomDateRangeStart.Year = startDate.Year;
// Set the end date to today.
DateTime endDate = DateTime.Today;
request.Time.CustomDateRangeEnd = new Date();
request.Time.CustomDateRangeEnd.Day = endDate.Day;
request.Time.CustomDateRangeEnd.Month = endDate.Month;
request.Time.CustomDateRangeEnd.Year = endDate.Year;
report.setTime(new ReportTime());
Calendar calendar = Calendar.getInstance();
report.getTime().setCustomDateRangeStart(new Date());
report.getTime().getCustomDateRangeStart().setMonth(1);
report.getTime().getCustomDateRangeStart().setDay(1);
report.getTime().getCustomDateRangeStart().setYear(calendar.get(Calendar.YEAR)-1);
report.getTime().setCustomDateRangeEnd(new Date());
report.getTime().getCustomDateRangeEnd().setMonth(12);
report.getTime().getCustomDateRangeEnd().setDay(31);
report.getTime().getCustomDateRangeEnd().setYear(calendar.get(Calendar.YEAR)-1);
$report->Time = new ReportTime();
$report->Time->PredefinedTime = null;
date_default_timezone_set('UTC');
$LastYear = date("Y") - 1;
$report->Time->CustomDateRangeStart = new Date();
$report->Time->CustomDateRangeStart->Month = 1;
$report->Time->CustomDateRangeStart->Day = 1;
$report->Time->CustomDateRangeStart->Year = $LastYear;
$report->Time->CustomDateRangeEnd = new Date();
$report->Time->CustomDateRangeEnd->Month = 12;
$report->Time->CustomDateRangeEnd->Day = 31;
$report->Time->CustomDateRangeEnd->Year = $LastYear;
report_time=reporting_service.factory.create('ReportTime')
custom_date_range_start=reporting_service.factory.create('Date')
custom_date_range_start.Day=1
custom_date_range_start.Month=1
custom_date_range_start.Year=int(strftime("%Y", gmtime()))-1
report_time.CustomDateRangeStart=custom_date_range_start
custom_date_range_end=reporting_service.factory.create('Date')
custom_date_range_end.Day=31
custom_date_range_end.Month=12
custom_date_range_end.Year=int(strftime("%Y", gmtime()))-1
report_time.CustomDateRangeEnd=custom_date_range_end
report_time.PredefinedTime=None
report_request.Time=report_time