Envoyer des demandes directes

Dans le cadre de votre mise en œuvre, nous vous encourageons à utiliser les exemples de code et bibliothèques clientes. Toutefois, si votre intégration avec l'API doit satisfaire des besoins spéciaux, comme l'utilisation d'une langue non prise en charge, vous pouvez envoyer des demandes directes en suivant la procédure ci-dessous.

Contenu

  1. Style d'appel
    1. REST dans l'API AdSense Management
  2. Format des données
  3. Autoriser des demandes
    1. Envoyer une demande

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 comme 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 Management

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

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

https://www.googleapis.com/adsense/v1.4/resourceID?parameters

où resourceID est l'identifiant d'un client publicitaire, d'un bloc d'annonces, 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 permet d'identifier la ressource sur laquelle vous travaillez, par exemple :

https://www.googleapis.com/adsense/v1.4/adclients
https://www.googleapis.com/adsense/v1.4/adclients/adClientId
https://www.googleapis.com/adsense/v1.4/adclients/adClientId/adunits
https://www.googleapis.com/adsense/v1.4/adclients/adClientId/adunits/adUnitId
https://www.googleapis.com/adsense/v1.4/adclients/adClientId/urlchannels
...

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

Voici quelques exemples d'utilisation de ce format dans l'API AdSense Management.

Répertorier les clients publicitaires :

GET https://www.googleapis.com/adsense/v1.4/adclients/

Répertorier les blocs d'annonces dans le client publicitaire "ca-pub-1234567890123456" :

GET https://www.googleapis.com/adsense/v1.4/adClients/ca-pub-1234567890123456/adunits

Format des données

JSON (JavaScript Object Notation) est un format de données 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, reportez-vous à json.org.

Autoriser des demandes

Chaque demande que votre application envoie à l'API AdSense Management 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

Toutes les demandes envoyées à l'API AdSense Management doivent être autorisées par un utilisateur authentifié.

Les détails de la procédure d'autorisation, ou "flux", pour OAuth 2.0 varient légèrement selon le type d'application que vous développez. La procédure générale suivante est valable pour tous les types d'applications :

  1. Lorsque vous créez votre application, vous l'enregistrez à l'aide de 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 Management dans Google Developers Console (si l'API n'est pas répertoriée dans 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 de consentement, dans lequel l'internaute autorise 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'applications, 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 Management :

Champ d'application Signification
https://www.googleapis.com/auth/adsense Accès en lecture et en écriture aux données AdSense
https://www.googleapis.com/auth/adsense.readonly Accès en lecture seule 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, accédez à la page Exemples de code et bibliothèques clientes.

Envoyer une demande

La dernière étape consiste à envoyer une demande d'API. Pour en savoir plus, consultez la documentation de référence.