Premiers pas

Ce document détaille les connaissances requises pour utiliser l'API Google Site Verification.

Présentation

L'API Google Site Verification est destinée aux développeurs qui souhaitent créer des applications ou des services qui automatisent le processus de validation de la propriété d'un site ou d'un domaine. C'est important, car certains services Google ne peuvent être utilisés que par les propriétaires de sites Web ou de domaines. Vous pouvez utiliser l'API Google Site Verification pour vous assurer que l'utilisateur authentifié est propriétaire du domaine ou du site. Il s'agit peut-être de la première étape pour provisionner de manière automatisée d'autres services Google.

Dans ce document, nous partons du principe que vous connaissez les concepts de la programmation Web et les formats de données Web, et que vous savez modifier automatiquement les fichiers ou les enregistrements DNS de votre site Web ou de votre domaine.

Présentation

Vous pouvez utiliser l'API Google Site Verification pour modifier les données de validation des sites Google d'un utilisateur. Les utilisateurs ne peuvent accéder à certains services Google que si leurs données de validation indiquent qu'ils sont propriétaires du domaine de site Web concerné. L'API vous permet de générer des jetons de validation pour les utilisateurs authentifiés, que votre code peut placer de différentes manières sur vos sites Web ou dans vos enregistrements de domaine en leur nom. Une fois le jeton en place, vous appelez l'API pour demander à Google de le rechercher. Si Google trouve le jeton, il enregistre l'utilisateur authentifié en tant que propriétaire du site Web ou du domaine. Vous pouvez également utiliser l'API pour modifier la liste des propriétaires au nom de l'utilisateur, ou pour retirer complètement la propriété d'un 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é.

Pour illustrer précisément le cas d'utilisation de cette API, supposons que vous proposiez un service d'hébergement Web. Vos utilisateurs souhaitent pouvoir accéder à la Search Console de Google pour obtenir des informations sur leur site. Pour y parvenir, Google doit savoir qu'il en est vraiment le propriétaire. Vous fournissez donc à vos utilisateurs une interface leur demandant de valider la propriété du site. Ils permettent à votre application d'accéder à leurs données de validation. Ils peuvent désormais exécuter du code qui demande un jeton en leur nom, le place dans un fichier sur la structure de leur site et demande à Google de le vérifier. Lorsque Google trouve le jeton, il octroie la propriété du site à l'utilisateur en mettant à jour ses données de validation. Ils peuvent désormais utiliser la Search Console pour obtenir les informations souhaitées.

Avant de commencer

Obtenir un compte Google

Vous devez vous assurer que vous avez configuré un compte Google. Nous vous recommandons d'utiliser un autre compte Google à des fins de développement et de test pour vous protéger contre toute perte de données accidentelle.

Se familiariser avec la validation de site

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

Découvrez comment autoriser les requêtes

Chaque requête envoyée par votre application à l'API Google Site Verification doit inclure un jeton d'autorisation. Ce jeton 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 paramètres d'autorisation sont gérés automatiquement.

Autoriser des requêtes avec OAuth 2.0

Toutes les requêtes adressé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") relative à 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 de consentement dans lequel l'internaute autorise 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 d'autres étapes, comme l'utilisation de jetons d'actualisation afin d'obtenir 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.

Informations sur le champ d'application OAuth 2.0 pour l'API Google Site Verification:

Niveau d'accès Signification
https://www.googleapis.com/auth/siteverification Accès complet en lecture aux sites déjà validés, 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 validés existants.

Pour demander l'accès via OAuth 2.0, votre application a besoin du champ d'application ainsi que des informations fournies par Google lors de son enregistrement (ID et 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 disponibles pour une grande variété de langages de programmation. Pour en savoir plus, accédez à la page Exemples de code et bibliothèques clientes.

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

concepts

Vous pouvez utiliser l'API Google Site Verification pour déterminer la propriété des types de ressources Web suivants:

  • Domaine:domaine ou sous-domaine. Le propriétaire d'un domaine est considéré comme le propriétaire de tous les sites et sous-domaines qui en font partie. 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'accès d'un site Web. Le propriétaire d'un site est considéré comme le propriétaire de tous les sites qu'il gère. 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".

Étant donné que la propriété d'un domaine s'applique plus largement que la propriété d'un site, nous vous recommandons de valider les domaines dans la mesure du possible.

Pour cela, votre application doit 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 le site Web ou le domaine. Une fois le jeton en place, votre application peut envoyer une requête à l'API Google Site Verification. Ce dernier recherche alors le jeton et enregistre sa propriété lorsqu'il est détecté.

Limites

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

  • Accès aux données pour l'utilisateur authentifié uniquement: toutes les opérations nécessitent l'authentification et l'autorisation de l'utilisateur.
  • Validation pour les utilisateurs authentifiés uniquement:l'API ne peut valider la propriété des sites ou domaines que pour le compte actuellement authentifié. Toutefois, l'utilisateur authentifié peut déléguer la propriété à d'autres utilisateurs une fois qu'il est propriétaire d'un site. Notez que tous les propriétaires sont informés par e-mail de toute modification apportée à la liste des propriétaires.
  • URL et noms de domaine normalisés uniquement. L'API Google Site Verification n'est pas compatible avec l'encodage IDN (International Domain Name). Veillez à normaliser l'ensemble des URL, noms de domaine et domaines d'adresse e-mail dans le jeu de caractères standard (RFC 1034 §3.5), en utilisant le Punycoding si nécessaire.

Méthodes et jetons de validation

L'API fournit des appels pour les phases de validation distinctes:

  • 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 chaque site.
  • Vérification de la présence du jeton de validation : un appel d'API distinct demande à Google de vérifier le jeton afin de confirmer que l'utilisateur authentifié est propriétaire d'un site.

Il existe plusieurs méthodes de validation d'un site Web ou d'un domaine que votre application peut utiliser. Celle que vous sélectionnez dépend de vos besoins. L'emplacement du jeton et le type de jeton 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 via son bureau d'enregistrement, à l'aide du jeton pour les données d'enregistrement. Le jeton est constitué de deux parties séparées par un espace: la première correspond au nom du nouvel enregistrement CNAME, la deuxième à la valeur du nouvel enregistrement CNAME.

DNS_TXT

Votre application crée un enregistrement TXT pour le domaine du propriétaire, éventuellement via son bureau d'enregistrement, à l'aide du 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:

File
Votre application place le jeton sous la forme d'un fichier sur le site Web du propriétaire. Vous devez créer un fichier nommé pour correspondre à la chaîne de 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 premier niveau de son site) avec le contenu suivant:

google-site-verification: google12cfc8677988bb4.html

Pour en savoir plus, consultez la documentation du centre d'aide sur la 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. Voici à quoi pourrait ressembler un fichier HTML contenant un jeton de validation Meta:

<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 à son compte Analytics, 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.

Pour comprendre les concepts fondamentaux et le flux de travail, vous pouvez d'abord essayer de valider quelques sites manuellement via 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 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 pouvez l'utiliser pour référencer cette ressource Web spécifique afin de la récupérer et de la modifier. Stockez le champ id de la sortie de l'opération list pour 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 ; les domaines 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 la copropriété ou révoquer la propriété 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 bénéficient de la copropriété peuvent également accorder cette autorisation, à condition qu'au moins un propriétaire validé et disposant d'un jeton sur le site soit enregistré.

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 en essayant simplement d'ajouter des ressources Web à la collection de ressources Web de l'utilisateur authentifié. Seuls les sites ou domaines validés ont bien été ajoutés à leur collection.

Comme indiqué dans la section Limites, les ressources Web n'appartenant pas à l'utilisateur authentifié ne sont pas accessibles via l'API Site Verification.