Premiers pas

Ce document fournit des informations générales sur l'utilisation de l'API Google Site Verification.

Introduction

L'API Google Site Verification est destinée aux développeurs qui souhaitent créer des applications ou des services automatiser le processus de validation de la propriété d'un site ou d'un domaine. C’est important, car certains Seuls les propriétaires de sites Web ou de domaines peuvent utiliser les services Google. Vous pouvez utiliser l'API Google Site Verification pour : confirmer que l'utilisateur authentifié est un propriétaire du domaine ou du site, éventuellement comme premier pour provisionner d'autres services Google par programmation.

Ce document part du principe que vous connaissez les concepts de programmation Web, les formats de données Web et modifier de manière programmatique les fichiers ou les enregistrements DNS de votre site Web ou domaine.

Présentation

Vous pouvez utiliser l'API Google Site Verification pour modifier les données Google Site Verification d'un utilisateur. Les utilisateurs ne peuvent accéder à certains services Google si les données de validation indiquent qu'il est le propriétaire un domaine de site Web particulier. Vous pouvez utiliser l'API afin de générer des jetons de validation pour les des utilisateurs, que votre code peut placer de différentes manières sur vos sites Web ou enregistrements de domaine sur leurs au nom de l'utilisateur. Une fois le jeton en place, vous appelez l'API pour demander à Google de vérifier la à partir d'un jeton d'accès. Si Google trouve le jeton, il enregistre l'utilisateur authentifié en tant que propriétaire du site Web. ou un domaine. Vous pouvez également utiliser l'API pour modifier la liste de propriété au nom de l'utilisateur ou pour supprimer la propriété du site.

Tous les appels d'API doivent être autorisés par un utilisateur authentifié, et tous les appels d'API sont exécutés dans le contexte du compte de l’utilisateur authentifié.

Prenons un exemple concret d'utilisation de cette API : vous fournissez un service d'hébergement Web. Vos utilisateurs souhaitent pouvoir utiliser la Search Console de Google pour obtenir des informations sur leur site. Pour cela, Google doit savoir vraiment le propriétaire. Vous fournissez donc à vos utilisateurs une interface qui leur demande de vérifier la propriété du site. Elles permettent à votre application d'accéder aux données de validation, exécutent maintenant le code qui demande un jeton en leur nom, le place dans un fichier sur leur site et demande à Google de la vérifier. Lorsque Google trouve le jeton, il accorde la propriété le site à l'utilisateur en mettant à jour ses données de validation. Il peut désormais utiliser la Search Console pour obtenir les informations qu'ils recherchent.

Avant de commencer

Obtenir un compte Google

Vous devez vous assurer d'avoir configuré un compte Google. Nous vous recommandons d'utiliser un compte Google distinct pour le développement et les tests afin d'éviter toute perte accidentelle de données.

Se familiariser avec la validation de site

Si vous ne connaissez pas les concepts de l'API Google Site Verification, nous vous recommandons de lire ce document, de tester l'interface utilisateur Verification et de lire la documentation d'aide associée avant de commencer à coder.

Découvrez comment autoriser les demandes

Chaque demande envoyée par votre application à l'API Google Site Verification doit inclure un jeton d'autorisation. Celui-ci permet également d'identifier votre application auprès de Google.

À propos des protocoles d'autorisation

Votre application doit autoriser les requêtes via le protocole OAuth 2.0. Les autres protocoles d'autorisation ne sont pas acceptés. Si votre application utilise la fonctionnalité Se connecter avec Google, certains aspects de l'autorisation sont traités pour vous.

Autoriser des requêtes avec OAuth 2.0

Toutes les demandes envoyées à l'API Google Site Verification doivent être autorisées par un utilisateur authentifié.

Les détails de la procédure d'autorisation (ou "flux") concernant OAuth 2.0 varient légèrement selon le type d'application que vous développez. La procédure générale suivante s'applique à tous les types d'applications :

  1. Lorsque vous créez votre application, vous l'enregistrez dans la console d'API Google. Google fournit ensuite des informations dont vous aurez besoin ultérieurement, dont un ID client et un code secret du client.
  2. Activez l'API Google Site Verification dans la console Google APIs. Si l'API ne figure pas dans la console, ignorez cette étape.
  3. Lorsque votre application doit accéder à des données utilisateur, elle demande à Google un champ d'application d'accès particulier.
  4. Google affiche alors un écran d'autorisation, dans lequel l'utilisateur est invité à autoriser votre application à demander certaines de ses données.
  5. Si l'utilisateur 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 requête.
  7. Dès lors que Google valide la requête et le jeton, les données demandées sont renvoyé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 concernant divers types d'applications, consultez la documentation OAuth 2.0 de Google.

Voici les informations concernant le champ d'application OAuth 2.0 pour l'API Google Site Verification:

Champ d'application Signification
https://www.googleapis.com/auth/siteverification Accès complet en lecture pour les sites validés existants, possibilité de valider de nouveaux sites.
https://www.googleapis.com/auth/siteverification.verify_only Possibilité de valider de nouveaux sites, pas d'accès en lecture pour les sites déjà validés.

Pour demander l'accès via OAuth 2.0, vous avez besoin du champ d'application ainsi que des informations fournies par Google lors de l'enregistrement de l'application (l'ID 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, explorez les bibliothèques clientes et les exemples de code présentés sur la page Installer les bibliothèques clientes.

Arrière-plan de l'API Google Site Verification

Concepts

Vous pouvez utiliser l'API Google Site Verification pour établir la propriété d'un utilisateur sur les types de ressources Web suivants:

  • Domaine:domaine ou sous-domaine. Le propriétaire d'un domaine est considéré comme le le propriétaire de tous les sites et sous-domaines appartenant à ce domaine. Par exemple, le propriétaire direct de bar.com est également considéré comme le propriétaire indirect de foo.bar.com.
  • Site:URL correspondant au domaine de base et au chemin d'un site Web. Le propriétaire d'un site est considéré comme le propriétaire de tous les sites de niveau inférieur. Par exemple, le propriétaire de "http://www.example.com/site" est également considéré comme le propriétaire de "http://www.example.com/site/sous-site".

La propriété des domaines s'appliquant plus largement que la propriété des sites, nous vous recommandons, dans la mesure du possible, d'effectuer la validation avec des domaines.

Pour confirmer que vous êtes le propriétaire d'un compte, vous devez d'abord demander un "jeton de validation" au nom de l'utilisateur. Le jeton de validation est une chaîne spéciale que votre code doit ensuite placer sur leur site Web ou leur domaine. Une fois le jeton en place, votre application peut envoyer une demande à l'API Google Site Verification, qui recherche le jeton et enregistre la propriété lorsqu'il est trouvé.

Limites

Pour des raisons techniques et de sécurité, l'API Google Site Verification applique certaines restrictions sur son utilisation:

  • Accès aux données pour l'utilisateur authentifié uniquement : toutes les opérations nécessitent une authentification et une autorisation de l'utilisateur.
  • Validation pour l'utilisateur authentifié uniquement:l'API peut uniquement valider la propriété des sites ou des domaines du compte actuellement authentifié. Cependant, l'utilisateur authentifié peut déléguer la propriété d'un site à d'autres utilisateurs une fois qu'il a été validé. Notez que tous les propriétaires reçoivent une notification par e-mail chaque fois que des modifications sont apportées à la liste des propriétaires.
  • URL normalisées et noms de domaine uniquement. L'API Google Site Verification n'est pas compatible avec le codage IDN (International Domain Name). Si nécessaire, veillez à normaliser tous les noms de domaine, URL et adresses e-mail selon le jeu de caractères standard du nom de domaine (RFC 1034, paragraphe 3.5) en utilisant Punycoding.

Méthodes et jetons de validation

L'API fournit des appels pour les différentes phases de validation:

  • Placer le jeton de validation : un appel d'API permet de récupérer un jeton de validation à placer sur le site de l'utilisateur authentifié. Si un utilisateur possède plusieurs sites, vous devez obtenir un jeton différent pour chacun d'eux.
  • Vérification de la présence du jeton de validation : un appel d'API distinct demande à Google de vérifier la présence du jeton de validation afin de s'assurer que l'utilisateur authentifié est propriétaire d'un site.

Il existe plusieurs méthodes pour valider un site Web ou un domaine que votre application peut utiliser : celle que vous sélectionnez dépend de ce qui convient le mieux à vos besoins. L'emplacement du jeton, ainsi que le type de jeton lui-même, dépendent de la méthode de validation que vous choisissez.

Méthode de validation du domaine

Deux méthodes de validation sont disponibles pour les domaines:

DNS_CNAME

Votre application crée un enregistrement CNAME pour le domaine du propriétaire, éventuellement par le biais de son bureau d'enregistrement de noms de domaine, en utilisant le jeton pour les données d'enregistrement. Le jeton se compose de deux parties séparées par un espace: la première partie correspond au nom du nouvel enregistrement CNAME, et la seconde à la valeur du nouvel enregistrement CNAME.

DNS_TXT

Votre application crée un enregistrement TXT pour le domaine du propriétaire, éventuellement par le biais de son bureau d'enregistrement de noms de domaine, en utilisant le jeton pour les données d'enregistrement.

Pour en savoir plus, consultez la documentation du centre d'aide sur la méthode de validation DNS.

Méthodes de validation des sites

Trois méthodes de validation sont disponibles pour les sites:

Fichier
Votre application place le jeton, sous la forme d'un fichier, sur le site Web du propriétaire. Vous devez créer un fichier dont le nom correspond à la chaîne du jeton, avec le contenu suivant: 
google-site-verification: token

Par exemple, si un utilisateur est propriétaire du site http://www.example.com/ et que le jeton renvoyé est google12cfc68677988bb4.html, il vous suffit de créer un fichier à l'adresse http://www.example.com/google12cfc68677988bb4.html (au niveau supérieur de son site), avec le contenu suivant:

google-site-verification: google12cfc8677988bb4.html

Pour en savoir plus, consultez l'article du centre d'aide intitulé Méthode de validation de fichier.

Méta

Votre application insère le jeton, sous la forme d'une balise HTML <meta>, dans l'élément <head> du fichier par défaut (index.html, default.html, etc.) au niveau supérieur du site du propriétaire. Un fichier HTML comportant un jeton de validation Meta peut se présenter comme suit:

<html>
  <head>
    <title>Awesome Dive Sites</title>
    <meta name="google-site-verification" content="-dhsoFQadgDKJR7BsB6bc1j5yfqjUpg_b-1pFjr7o3x" />
  </head>
  <body>
    ...

Pour en savoir plus, consultez la documentation du centre d'aide sur la méthode de validation Meta.

Analytics

Votre application utilise un code de suivi Google Analytics existant qui figure déjà sur le site Web du propriétaire. Le code de suivi doit appartenir au compte Analytics du client et l'extrait de code doit se trouver dans la balise HEAD pour fonctionner. Pour en savoir plus, consultez la documentation du centre d'aide sur la méthode de validation Analytics.

Tag Manager

Votre application utilise un code de conteneur Google Tag Manager existant qui figure déjà sur le site Web du propriétaire. Le code du conteneur doit appartenir à son compte Tag Manager. Pour en savoir plus, consultez la documentation du centre d'aide sur la méthode de validation Tag Manager.

Il peut être utile de comprendre les concepts fondamentaux et le workflow en essayant d'abord de valider manuellement quelques sites avec l'interface utilisateur de validation de site.

Modèle de données

Ressource Web

L'API Google Site Verification applique la sémantique REST (HTTP GET, POST, etc.) aux entités appelées "ressources Web". Une ressource Web est un site Web ou un domaine appartenant à l'utilisateur authentifié.

Voici un exemple de ressource Web:

{
  "owners": [
    "myself@example.com",
    "another@example.com"
  ],
  "id": "http%3A%2F%2Fwww.example.com%2F",
  "site": {
    "identifier": "http://www.example.com/",
    "type": "SITE"
  }
}

Le champ id est un identifiant unique pour cette ressource Web. Vous l'utilisez pour référencer cette ressource Web spécifique à des fins de récupération et de modification. Stockez le champ id à partir du résultat de l'opération list pour pouvoir l'utiliser ultérieurement comme identifiant.

L'objet site contient l'URL ou le nom de domaine de la ressource Web, ainsi que le type de la ressource. Les sites sont spécifiés avec le type SITE. sont spécifiés avec le type INET_DOMAIN.

Le tableau owners est la liste complète des propriétaires de la ressource Web, représentés par leurs adresses e-mail. En ajoutant ou en supprimant des adresses e-mail de la liste des propriétaires, l'utilisateur authentifié peut accorder ou révoquer la propriété pour d'autres utilisateurs. Les propriétaires supplémentaires qui ont placé leurs propres jetons sur le site ou le domaine apparaissent également dans la liste des propriétaires, avec leurs copropriétaires.

Les utilisateurs qui ont obtenu la copropriété peuvent également l'accorder, à condition qu'au moins un propriétaire validé disposant d'un jeton soit présent sur le site.

Collection de ressources Web

La collection de ressources Web est une liste complète de toutes les ressources Web appartenant à l'utilisateur authentifié. Vous pouvez valider la propriété de sites ou de domaines simplement en essayant d'ajouter des ressources Web à la collection de ressources Web de l'utilisateur authentifié. Seuls les sites ou domaines validés ont été ajoutés à la collection.

Comme indiqué précédemment dans la section Limites, les ressources Web qui appartiennent à des utilisateurs autres que l'utilisateur authentifié ne sont pas accessibles via l'API Site Verification.