YouTube Reporting API - System-Managed Reports

YouTube génère automatiquement un ensemble de rapports sur les revenus publicitaires gérés par le système pour les propriétaires de contenu qui ont accès aux rapports correspondants dans Creator Studio. Ils sont conçus pour fournir un accès programmatique aux données qui sont également disponibles dans des rapports téléchargeables manuellement, accessibles dans le menu "Rapports" de YouTube Studio.

Remarque:L'API permet d'accéder à un ensemble de rapports différent de celui de Creator Studio, bien qu'ils contiennent des données similaires. Les rapports de l'API peuvent comporter des champs différents de ceux des rapports Creator Studio. De plus, ils peuvent utiliser des noms de champs différents.

Étant donné que YouTube génère automatiquement des rapports gérés par le système, le processus de récupération de ces rapports est différent de celui utilisé pour les rapports de données groupées de YouTube Analytics, disponibles via l'API.

Récupérer des rapports

Pour récupérer des rapports gérés par le système via l'API, procédez comme suit.

Étape 1: Récupérer les identifiants d'autorisation

Toutes les requêtes de l'API YouTube Reporting doivent être autorisées. Le guide sur les autorisations explique comment utiliser le protocole OAuth 2.0 pour récupérer des jetons d'autorisation.

Les requêtes de l'API YouTube Reporting utilisent les champs d'application d'autorisation suivants:

Niveaux d'accès
https://www.googleapis.com/auth/yt-analytics.readonly Affichez les rapports YouTube Analytics sur vos contenus YouTube. Ce champ d'application permet d'accéder aux métriques sur l'activité des utilisateurs, telles que le nombre de vues et le nombre de notes.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Consultez les rapports financiers YouTube Analytics sur vos contenus YouTube. Ce champ d'application donne accès aux métriques sur l'activité des utilisateurs, ainsi qu'aux métriques sur les revenus estimés et les performances des annonces.

Étape 2: Récupérez l'ID de tâche pour le rapport souhaité

Appelez la méthode jobs.list pour récupérer la liste des tâches gérées par le système. Définissez le paramètre includeSystemManaged sur true.

La propriété reportTypeId de chaque ressource Job renvoyée identifie le type de rapport géré par le système associé à cette tâche. Votre application a besoin de la valeur de propriété id provenant de la même ressource à l'étape suivante.

Le document Rapports répertorie les rapports disponibles, leurs ID de type de rapport et les champs qu'ils contiennent. Vous pouvez également utiliser la méthode reportTypes.list pour récupérer la liste des types de rapports compatibles.

Étape 3: Récupérez l'URL de téléchargement du rapport

Appelez la méthode jobs.reports.list pour récupérer la liste des rapports créés pour la tâche. Dans la requête, définissez le paramètre jobId sur l'ID de tâche du rapport que vous souhaitez récupérer.

Vous pouvez filtrer la liste des rapports en utilisant l'un ou l'ensemble des paramètres suivants:

  • Utilisez le paramètre createdAfter pour indiquer que l'API ne doit renvoyer que les rapports créés après un délai spécifié. Ce paramètre permet de s'assurer que l'API ne renvoie que des rapports que vous n'avez pas encore traités.

  • Utilisez le paramètre startTimeBefore pour indiquer que la réponse de l'API ne doit contenir des rapports que si les données les plus anciennes du rapport sont antérieures à la date spécifiée. Alors que le paramètre createdAfter concerne l'heure de création du rapport, cette date concerne les données du rapport.

  • Utilisez le paramètre startTimeAtOrAfter pour indiquer que la réponse de l'API ne doit contenir des rapports que si les données les plus anciennes du rapport datent de la date spécifiée ou sont postérieures à celle-ci. Comme pour le paramètre startTimeBefore, cette valeur correspond aux données du rapport, et non à l'heure de sa création.

La réponse de l'API contient une liste de ressources Report pour ce job. Chaque ressource fait référence à un rapport contenant des données sur une période unique.

  • Les propriétés startTime et endTime de la ressource identifient la période couverte par les données du rapport.
  • La propriété downloadUrl de la ressource identifie l'URL à partir de laquelle le rapport peut être extrait.

  • La propriété createTime de la ressource spécifie la date et l'heure de génération du rapport. Votre application doit stocker cette valeur et l'utiliser pour déterminer si les rapports précédemment téléchargés ont changé.

Étape 4: Téléchargez le rapport

Envoyez une requête HTTP GET au downloadUrl obtenu à l'étape 4 pour récupérer le rapport.

Rapports de traitement

Bonnes pratiques

Les applications qui utilisent l'API YouTube Reporting doivent toujours respecter les pratiques suivantes:

  • Utilisez la ligne d'en-tête d'un rapport pour déterminer l'ordre des colonnes. Par exemple, ne partez pas du principe que les vues sont la première statistique affichée dans un rapport simplement parce que c'est la première statistique listée dans la description d'un rapport. Servez-vous plutôt de la ligne d'en-tête du rapport pour déterminer quelle colonne contient ces données.

  • Conservez une trace des rapports que vous avez téléchargés afin d'éviter qu'un même rapport soit traité plusieurs fois. La liste suivante suggère deux méthodes pour y parvenir.

    • Lorsque vous appelez la méthode reports.list, utilisez le paramètre createdAfter pour ne récupérer que les rapports créés après une certaine date. (Omettez le paramètre createdAfter la première fois que vous récupérez les rapports.)

      Chaque fois que vous récupérez et traitez des rapports, conservez l'horodatage correspondant à la date et à l'heure de la création du rapport le plus récent. Ensuite, mettez à jour la valeur du paramètre createdAfter à chaque appel successif de la méthode reports.list pour vous assurer que vous ne récupérez que de nouveaux rapports, y compris ceux avec des données remplies, chaque fois que vous appelez l'API.

      Par mesure de précaution, avant de récupérer un rapport, vérifiez également que son ID ne figure pas déjà dans votre base de données.

    • Stockez l'ID de chaque rapport que vous avez téléchargé et traité. Vous pouvez également stocker d'autres informations, telles que la date et l'heure de génération de chaque rapport, ou les valeurs startTime et endTime du rapport. Ces informations permettent d'identifier la période pour laquelle le rapport contient des données. Pour les rapports qui récupèrent des données groupées pour YouTube Analytics, chaque tâche contiendra probablement de nombreux rapports, car chaque rapport contient des données sur une période de 24 heures. Les jobs gérés par le système qui couvrent des périodes plus longues ont moins de rapports.

      Utilisez l'ID du rapport pour identifier les rapports que vous devez encore télécharger et importer. Toutefois, si deux nouveaux rapports présentent les mêmes valeurs de propriétés startTime et endTime, importez uniquement le rapport avec la valeur createTime la plus récente.

Caractéristiques du rapport

Les rapports d'API sont des fichiers .csv avec versions gérées (valeurs séparées par une virgule) présentant les caractéristiques suivantes:

  • Chaque rapport contient des données pour une période unique allant de minuit (heure du Pacifique) à la date de début du rapport à 23h59 (heure du Pacifique) à la date de fin du rapport.

  • Les données du rapport ne sont pas triées.