La méthode reportData.query permet de récupérer les données de rapport de manière synchrone. Contrairement au service Reports standard, qui génère des rapports basés sur des fichiers (CSV ou Excel), cette méthode renvoie des données JSON structurées directement dans la réponse. Il élimine le besoin de définir, de créer et d'enregistrer une ressource Report à l'avance, ce qui le rend idéal pour l'exploration et la récupération de données en temps réel.
Présentation
Consultez ce guide pour vous familiariser avec l'utilisation de ce point de terminaison afin d'interroger vos données de reporting Campaign Manager 360.
Préparer la demande
Créez un ReportDataQueryRequest en spécifiant les dimensions, les métriques, la plage de dates, les filtres et les critères de tri.
REST
{
"body": {
"dateRange": "LAST_7_DAYS",
"dimensionNames": [
"advertiser",
"campaign"
],
"metricNames": [
"impressions",
"clicks"
],
"sortBys": [
{
"name": "clicks",
"sortOrder": "DESCENDING"
}
],
"maxResults": 100
}
}
dateRange- Objet
DateRangespécifiant la période de la requête. Il peut s'agir d'une plage de dates personnalisée ou relative. dimensionNames- Liste des noms de dimensions standards à regrouper.
metricNames- Obligatoire. Liste des noms de métriques standards à inclure.
dimensionFilters- Liste des objets DimensionValue utilisés pour filtrer les données du rapport. Utilisez-le pour limiter les résultats de la requête à des valeurs spécifiques d'une dimension.
sortBys- Configurations de tri pour les dimensions ou les métriques. Chaque configuration inclut le nom du champ et un ordre de tri.
maxResults- Nombre maximal de lignes à renvoyer par page (par défaut :
100, max. :1000).
Pagination
Le champ maxResults contrôle le nombre de résultats renvoyés dans une même réponse. Par exemple, si vous définissez maxResults sur 10, l'API renverra au maximum 10 résultats. Il est possible que l'API renvoie moins de 10 résultats si le nombre de résultats correspondant à votre requête est inférieur à 10.
Si des résultats supplémentaires sont disponibles, la réponse inclut un nextPageToken. Pour récupérer la page de résultats suivante, renvoyez la même requête avec le champ pageToken défini sur ce jeton. Conservez tous les autres paramètres de requête.
Envoyer la requête
Envoyez une requête HTTP POST au point de terminaison reportdata/query :
POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query
Assurez-vous que votre demande est authentifiée avec des identifiants OAuth 2.0 standards et les habilitations nécessaires. Pour en savoir plus, consultez Autoriser les requêtes.
Réponse positive
Une requête réussie renvoie une réponse HTTP 200 OK avec une charge utile JSON contenant columnHeaders, rows et totalRow.
{
"columnHeaders": [
{ "name": "advertiser", "type": "DIMENSION" },
{ "name": "campaign", "type": "DIMENSION" },
{ "name": "impressions", "type": "METRIC" },
{ "name": "clicks", "type": "METRIC" }
],
"rows": [
{
"values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
},
{
"values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
}
],
"totalRow": {
"values": [ "", "", "150831", "422" ]
},
"nextPageToken": "1234567890"
}
columnHeaders- Nom et types (
DIMENSIONouMETRIC) des champs renvoyés. rows- : liste d'objets
ReportDataRowcontenant les résultats de la requête. Les valeurs de chaîne de chaque ligne s'alignent par position aveccolumnHeaders. totalRow- Une seule ligne d'agrégation représentant la somme de toutes les métriques correspondantes. Les champs de dimension et les métriques qui ne peuvent pas être additionnés (par exemple, les métriques de couverture telles que
uniqueReachTotalReach) sont vides ("") dans cette ligne. nextPageToken- Jeton utilisé dans une requête ultérieure pour récupérer la page suivante si des lignes supplémentaires existent.
Latence et délais avant expiration
Comme il s'agit d'un point de terminaison synchrone, les requêtes s'exécutent immédiatement et les données sont renvoyées directement dans la réponse (dans la limite de pagination maxResults).
Les requêtes ont une durée d'exécution maximale de 60 secondes. Si une requête dépasse cette limite, l'API met fin à l'opération et renvoie une erreur HTTP 503 Service
Unavailable.
Si vous rencontrez cette erreur, essayez de réduire la plage de dates, d'affiner les filtres (par exemple, en filtrant par annonceurs ou campagnes spécifiques) ou de diminuer le nombre de dimensions et de métriques demandées. Vous pouvez également exécuter un Report à l'aide de reports.run pour générer un fichier de rapport téléchargeable de manière asynchrone.
Limites et contraintes des requêtes
Le point de terminaison reportdata.query applique plusieurs limites pour garantir des réponses fiables. Les requêtes qui ne respectent pas ces contraintes sont rejetées avec une réponse HTTP 400 Bad Request.
Limites de la plage de dates
- Pour les périodes personnalisées, la
startDatedoit se situer dans la période de disponibilité des données pour le type de données du rapport demandé. Pour en savoir plus, consultez la section Disponibilité des données.
Contraintes liées aux métriques et aux dimensions
- Au moins une métrique doit être fournie dans
metricNames. - Les métriques et les dimensions des listes
metricNamesetdimensionNamesdoivent être uniques. - Les métriques et dimensions portant le libellé Téléchargement uniquement ne peuvent pas être utilisées dans ces requêtes.
Limites de quota
Les requêtes envoyées à ce point de terminaison consomment les quotas suivants :
- Limite de débit par utilisateur : 120 requêtes par minute et par utilisateur (2 RPS)
- Limite quotidienne par projet : 10 000 requêtes par jour et par projet
Les requêtes qui dépassent ces limites échouent et renvoient une erreur HTTP 429 Too Many Requests. Si vous parcourez les résultats, chaque demande de nouvelle page (à l'aide du paramètre pageToken) est comptabilisée comme une requête distincte et consomme une partie de ce quota.