Premiers pas

Ce document s'adresse aux développeurs qui souhaitent utiliser l'API AdSense Host pour obtenir des informations sur leur compte AdSense. Il suppose que vous connaissez les concepts de programmation Web ainsi que les formats de données Web.

Sommaire

Avant de commencer

Créer un compte AdSense

Vous avez besoin d'un compte AdSense à des fins de test. Si vous possédez déjà un compte de test, vous êtes prêt et pouvez accéder à l'interface utilisateur AdSense afin de configurer, modifier ou afficher vos données de test.

Se familiariser avec AdSense

Si vous ne connaissez pas les concepts AdSense, lisez l'introduction à AdSense et familiarisez-vous avec l'interface utilisateur avant de commencer à écrire votre code.

Enregistrer votre application

Pour pouvoir utiliser l'API AdSense Host, vous devez enregistrer auprès de Google l'application que vous développez :

  1. Accédez à la console des API.
  2. Connectez-vous à votre compte Google ou créez un compte.
  3. Créez un projet.
  4. Dans le projet que vous venez de créer, cliquez sur le lien "Demander l'accès" sous l'API AdSense Host.

Pour les applications OAuth 2.0, veuillez suivre les étapes supplémentaires décrites à la page Utilisation d'OAuth 2.0 pour accéder aux API Google.

Remarque : Pour vous inscrire, vous devez utiliser votre compte développeur, c'est-à-dire le compte que les utilisateurs de votre application doivent identifier comme celui du développeur de l'application. Il n'est pas nécessaire que ce compte soit associé à des informations de connexion AdSense, car les utilisateurs auront accès à leur propre compte lorsqu'ils utiliseront l'application.

Comprendre l'API AdSense Host

Concepts de base

L'API AdSense Host repose sur plusieurs concepts AdSense fondamentaux :

  • Les clients publicitaires : les clients publicitaires représentent l'association entre un compte AdSense et un produit AdSense, par exemple des annonces AdSense pour les pages de contenu ou du Réseau de Recherche. Un compte AdSense peut être associé à plusieurs clients publicitaires.
  • Les critères : ce sont des outils qui permettent d'effectuer le suivi des performances d'une page ou d'un domaine spécifique.
  • Les rapports : ils vous donnent un aperçu de vos revenus, ainsi que des facteurs qui les influencent. Ils peuvent être générés pour l'intégralité d'un compte ou pour une partie de votre inventaire, à l'aide de critères.

Opérations disponibles

Les opérations actuellement admises par l'API sont décrites dans le tableau ci-dessous.

Opération Description Mappages HTTP REST
list Répertorier toutes les ressources d'une collection GET sur un URI de collection
get Obtenir une ressource spécifique GET sur un URI de ressource
generate Générer un ensemble de résultats pour la ressource spécifiée Utilisée uniquement pour les rapports GET/POST sur un URI de collection, où vous transmettez la ressource en tant que définition pour la génération

Chaque opération requiert une authentification.

Style d'appel

REST est un style d'architecture logicielle qui permet de demander et modifier des données de manière pratique et cohérente.

Le terme REST est l'acronyme de Representational State Transfer. Dans le contexte des API Google, il désigne l'utilisation de verbes HTTP pour extraire et modifier des représentations de données stockées par Google.

Dans un système RESTful, les ressources sont stockées dans une banque de données. Un client envoie une demande pour que le serveur exécute une action particulière (par exemple la création, l'extraction, la mise à jour ou la suppression d'une ressource), et le serveur exécute l'action et envoie une réponse, souvent sous la forme d'une représentation de la ressource spécifiée.

Dans les API RESTful de Google, le client spécifie une action à l'aide d'un verbe HTTP tel que POST, GET, PUT ou DELETE. Il spécifie une ressource avec un URI globalement unique dont la forme est la suivante :

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Étant donné que toutes les ressources d'API possèdent des URI uniques accessibles via HTTP, REST permet la mise en cache des données, et son fonctionnement est optimisé pour l'infrastructure répartie du Web.

Pour en savoir plus sur REST, vous pouvez consulter les documents de tiers suivants :


REST dans l'API AdSense Host

Les opérations acceptées sont mappées directement à des verbes HTTP REST, comme expliqué à la section Opérations de l'API AdSense Host.

Le format spécifique pour les URI de l'API AdSense Host est le suivant :

https://www.googleapis.com/adsensehost/v4.1/resourceID?parameters

resourceID est l'identifiant d'un client publicitaire, d'un critère d'URL, d'un critère personnalisé ou d'une collection de rapports, et parameters représente les paramètres à appliquer à la demande.

Le format des extensions de chemin resourceID vous permet d'identifier la ressource en cours d'utilisation. Par exemple :

https://www.googleapis.com/adsensehost/v4.1/adclients
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId/urlchannels
...

L'ensemble complet des URI utilisés pour chaque opération disponible dans l'API est synthétisé dans la documentation de référence de l'API AdSense Host.

L'exemple ci-dessous illustre ce fonctionnement dans l'API AdSense Host.

Répertorier les clients publicitaires :

GET https://www.googleapis.com/adsensehost/v4.1/adclients/

Format des données

JSON (JavaScript Object Notation) est un format de données commun qui ne dépend pas d'un langage et qui fournit une représentation textuelle simple de structures de données arbitraires. Pour en savoir plus, consultez le site json.org.

Envoyer des demandes

Autoriser des demandes

Chaque demande que votre application envoie à l'API AdSense Host doit inclure un jeton d'autorisation. Le jeton identifie également votre application auprès de Google.

À propos des protocoles d'autorisation

Votre application doit utiliser OAuth 2.0 pour autoriser les requêtes. Les autres protocoles d'autorisation ne sont pas compatibles.

Autoriser des demandes avec OAuth 2.0

Chaque demande envoyée à l'API AdSense Host doit être autorisée par un utilisateur authentifié.

Le détail de la procédure (ou "flux") d'autorisation pour OAuth 2.0 varie en fonction du type d'application que vous codez. La procédure générale suivante est valable pour tous les types d'applications :

  1. Lorsque vous créez votre application, vous enregistrez cette dernière avec la Google Developers Console. Google vous fournit alors des informations dont vous aurez besoin ultérieurement, comme un numéro client et un "secret client".
  2. Activez l'API AdSense Host dans la Google Developers Console (si l'API n'est pas répertoriée dans la Google Developers Console, ignorez cette étape).
  3. Lorsque votre application requiert l'accès aux données utilisateur, elle demande à Google un champ d'accès particulier.
  4. Google affiche alors un écran d'acceptation invitant l'internaute à autoriser votre application à demander certaines de ses données.
  5. Si l'internaute accepte, Google attribue à votre application un jeton d'accès temporaire.
  6. Votre application demande des données utilisateur en joignant le jeton d'accès à la demande.
  7. Dès lors que le système Google valide la demande et le jeton, il renvoie les données sollicitées.

Certains flux comportent des étapes supplémentaires, comme l'utilisation de jetons d'actualisation en vue de l'acquisition de nouveaux jetons d'accès. Pour en savoir plus sur les flux pour divers types d'application, consultez la documentation OAuth 2.0 de Google.

Voici les informations concernant le paramètre d'accès OAuth 2.0 pour l'API AdSense Host :

Paramètres d'accès Signification
https://www.googleapis.com/auth/adsensehost Accès en lecture et en écriture aux données AdSense

Pour demander l'accès au moyen d'OAuth 2.0, votre application a besoin du paramètre d'accès et des informations fournies par Google lors de l'enregistrement de l'application (l'identifiant client et le code secret du client, par exemple).

Conseil : Les bibliothèques clientes des API Google peuvent gérer une partie de la procédure d'autorisation à votre place. Elles sont proposées pour une grande variété de langages de programmation. Pour en savoir plus, consultez la page Bibliothèques et exemples de code.

Consultez la section OAuth 2.0 pour obtenir plus d'informations.

Envoyer une demande

La dernière étape consiste à envoyer la demande d'API. Si vous n'utilisez pas de bibliothèque cliente, nous vous invitons à consulter la documentation de référence.

Néanmoins, l'utilisation de bibliothèques clientes simplifie considérablement cette tâche. Reportez-vous à la section Bibliothèques et exemples afin d'obtenir des instructions complètes pour envoyer votre première demande avec la bibliothèque cliente Java, Python, PHP ou JavaScript.

OAuth 2.0

Dans l'API AdSense Host, l'authentification et l'autorisation sont gérées par OAuth 2.0. Toutefois, en raison de certaines particularités du modèle d'utilisation AdSense Host, les processus peuvent être légèrement différents de ceux que vous avez l'habitude d'utiliser dans les autres API Google.

Participants

Les entités qui participent à une requête OAuth 2.0 sont au nombre de trois :

  • L'utilisateur, qui accorde l'accès aux données personnelles
  • Le développeur, qui demande l'accès aux données de l'utilisateur par le biais de l'application
  • Google, qui authentifie les parties et fournit le service d'API

Toutefois, dans le cas de l'API AdSense Host, l'utilisateur et le développeur sont en fait la même personne. En effet, en tant que développeur, vous utiliserez l'API pour accéder à votre propre compte AdSense et, par son intermédiaire, aux comptes de vos éditeurs.

Créer un projet

Vous pouvez créer des projets sur la page de la console des API.
Figure 1 : Nouveau projet dans la console des API

Avant de commencer, vous devez créer un projet dans la console des API, comme vous le feriez dans toute autre API Google. Le compte Google dont vous vous servez pour créer le projet de développeur doit être ajouté à la liste blanche pour permettre l'accès à l'API AdSense Host. Par conséquent, assurez-vous d'utiliser le compte bac à sable qui a été créé pour vous au moment de l'inscription ou votre compte de production AdSense si votre mise en œuvre de l'API est déjà active.

L'onglet "Services" vous permet de choisir les API actives dans votre projet.
Figure 2 : API activées et désactivées pour un projet

Pour plus d'informations sur la création de projets d'API Google, consultez la documentation relative à la console des API.

Configurer l'accès à l'API

Une fois que vous disposez d'un projet, vous devez activer l'accès à l'API dans ce dernier. Pour ce faire, créez un numéro client OAuth 2.0.

Vous pouvez créer des clients OAuth 2.0 dans l'onglet "Accès API".
Figure 3 : Création d'un client OAuth 2.0 dans la console des API

Plusieurs possibilités s'offrent à vous, mais nous vous recommandons de créer un projet de type Application installée, car les étapes suivantes sont plus simples.

Une seule authentification et un stockage permanent

Vous devez à présent vous authentifier à l'aide de votre propre compte AdSense. Pour ce faire, vous pouvez utiliser un petit script ou une application test (consultez nos exemples de code).

Une fois que vous êtes authentifié, veillez à stocker le jeton d'actualisation que vous avez obtenu lors de l'étape d'autorisation. Il s'agit d'un jeton de longue durée, qui n'arrivera pas à expiration tant que l'accès n'aura pas été explicitement révoqué. Et comme vous êtes l'utilisateur, il n'y a aucune raison que vous révoquiez l'accès à votre propre application !

Vous devez enregistrer le jeton d'actualisation dans le magasin de données de votre application pour toutes les futures demandes d'authentification.

Utiliser le jeton enregistré dans votre application

Une fois que vous disposez d'un jeton d'actualisation, peu importe qu'il ait été généré dans le flux d'une application de serveur Web ou d'une application installée. Vous pouvez simplement l'utiliser pour effectuer des demandes de jetons d'actualisation afin de bénéficier de nouveaux jetons d'accès si nécessaire. Si vous utilisez l'une de nos bibliothèques clientes, consultez la documentation pour savoir comment spécifier vos propres jetons. Vous serez peut-être amené à modifier un fichier généré automatiquement ou une entrée de base de données.

Conclure

Au final, le flux OAuth 2.0 n'est exécuté qu'une seule fois. Ensuite, toutes les demandes sont effectuées en arrière-plan, sans aucune intervention manuelle de l'utilisateur final de votre site (l'éditeur) ni de vous-même, le développeur.

Annonces

Restez informé sur les nouvelles versions, les nouvelles fonctionnalités et les mises à jour de service importantes en consultant les annonces concernant l'API AdSense.

Envoyer des commentaires concernant…