YouTube Reporting API - Get Bulk Data 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. Ces rapports sont conçus pour fournir un accès programmatique aux données qui sont également disponibles dans les rapports téléchargeables manuellement accessibles dans le menu "Rapports" de YouTube Creator Studio.

Remarque : L'API donne accès à un ensemble de rapports différent de celui de Creator Studio, bien que les rapports contiennent des données similaires. Les rapports de l'API peuvent comporter des champs différents et utiliser des noms de champs différents de ceux des rapports Creator Studio.

Étant donné que YouTube génère automatiquement des rapports gérés par le système, la procédure pour les récupérer est différente de celle des rapports sur les données groupées YouTube Analytics disponibles via l'API.

Récupérer des rapports

Les étapes suivantes expliquent comment récupérer des rapports gérés par le système via l'API.

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

Toutes les requêtes envoyées à l'API YouTube Reporting doivent être autorisées. Le guide d'autorisation 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 votre contenu YouTube. Ce champ d'application permet d'accéder aux métriques d'activité des utilisateurs, comme le nombre de vues et le nombre de notes.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Affichez les rapports monétaires YouTube Analytics concernant votre contenu YouTube. Ce champ d'application permet d'accéder aux métriques sur l'activité des utilisateurs, ainsi qu'aux métriques estimées sur les revenus et les performances des annonces.

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

Appelez la méthode jobs.list pour récupérer la liste des jobs gérés 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é à ce job. Votre application aura besoin de la valeur de la propriété id de la même ressource à l'étape suivante.

Le document Rapports liste les rapports disponibles, leurs ID de type 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 le job. Dans la requête, définissez le paramètre jobId sur l'ID du rapport que vous souhaitez récupérer.

Vous pouvez filtrer la liste des rapports à l'aide de tout ou partie des paramètres suivants :

  • Utilisez le paramètre createdAfter pour indiquer que l'API ne doit renvoyer que les rapports créés après une heure spécifiée. Ce paramètre peut être utilisé pour s'assurer que l'API ne renvoie que les 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 de rapports que si la date la plus ancienne du rapport est antérieure à la date spécifiée. Alors que le paramètre createdAfter concerne l'heure à laquelle le rapport a été créé, 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 de rapports que si la date la plus ancienne du rapport est égale ou postérieure à la date spécifiée. Comme le paramètre startTimeBefore, la valeur de ce paramètre correspond aux données du rapport et non à l'heure à laquelle il a été créé.

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 pour 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 récupéré.
  • 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 été modifiés.

Étape 4 : Téléchargez le rapport

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

Traitement des rapports

Bonnes pratiques

Les applications qui utilisent l'API YouTube Reporting doivent toujours suivre ces pratiques :

  • Utilisez la ligne d'en-tête d'un rapport pour déterminer l'ordre des colonnes du rapport. Par exemple, ne partez pas du principe que views sera la première métrique renvoyée dans un rapport simplement parce qu'elle est la première métrique listée dans la description d'un rapport. Utilisez plutôt la ligne d'en-tête du rapport pour déterminer la colonne contenant ces données.

  • Conservez un enregistrement des rapports que vous avez téléchargés pour éviter de traiter plusieurs fois le même rapport. La liste suivante vous propose quelques façons de procéder.

    • 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 des rapports.)

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

      Par mesure de sécurité, 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 des informations supplémentaires, comme la date et l'heure de génération de chaque rapport, ou les startTime et endTime du rapport, qui identifient ensemble 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 job comportera probablement de nombreux rapports, car chacun d'eux contient des données pour une période de 24 heures. Les jobs gérés par le système qui couvrent des périodes plus longues génèrent 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 ont les mêmes valeurs de propriété startTime et endTime, n'importez que celui dont la valeur createTime est la plus récente.

Caractéristiques des rapports

Les rapports de l'API sont des fichiers .csv (valeurs séparées par une virgule) qui présentent les caractéristiques suivantes :

  • Chaque rapport contient des données pour une période unique allant de 00h00 à 23h59, heure du Pacifique, aux dates de début et de fin du rapport.

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