Como começar

Este documento detalha o conhecimento prévio que você precisa para usar a API Google Site Verification.

Introdução

A API de verificação de site do Google destina-se a desenvolvedores que desejam criar aplicativos ou serviços que automatizar o processo de verificação da propriedade de um site ou domínio. Isso é importante, pois alguns Os Serviços do Google só podem ser usados por proprietários de sites ou domínios. É possível usar a API Google Site Verification para validar se o usuário autenticado é um proprietário do domínio ou site, possivelmente como o primeiro o provisionamento de outros serviços do Google de modo programático.

Este documento pressupõe que você esteja familiarizado com conceitos de programação e formatos de dados da web e modificar de forma programática os arquivos ou registros DNS do site ou domínio.

Visão geral

Use a API Google Site Verification para modificar os dados de verificação de site do Google de um usuário. Os usuários só podem acessar determinados Serviços do Google se os dados de verificação mostrarem que eles são os proprietários dos domínio de site específico. Você pode usar a API para gerar tokens de verificação para que o código pode colocar de várias maneiras nos sites ou registros de domínio nome de usuário. Assim que o token estiver no lugar, você fará uma chamada para a API para pedir ao Google para verificar a com base no token correto anterior. Se o Google encontra o token, ele registra o usuário autenticado como proprietário do site. ou domínio. Também é possível usar a API para modificar a lista de propriedade em nome do usuário ou para remover completamente a propriedade do site.

Todas as chamadas de API precisam ser autorizadas por um usuário autenticado e todas as chamadas de API são executadas. no contexto da conta do usuário autenticado.

Como um exemplo concreto de quando você pode usar essa API, suponha que você forneça um serviço de hospedagem na Web. Seus usuários querem poder usar o Search Console do Google para conseguir informações sobre o site. Para que eles façam isso, o Google precisa saber dominá-lo de verdade. Então, você fornece aos seus usuários uma interface que solicita que eles verifiquem a propriedade do site. Elas dão ao seu aplicativo acesso aos dados de verificação delas e podem agora executam um código que solicita um token em nome deles e o coloca em um arquivo no site e pede ao Google para verificar isso. Quando o Google encontra o token, ele concede a propriedade de do site para o usuário, atualizando seus dados de verificação. Agora a empresa pode usar o Search Console para as informações desejadas.

Antes de começar

Criar uma Conta do Google

Confira se você tem uma Conta do Google configurada. Recomendamos que você use uma Conta do Google separada para fins de desenvolvimento e teste para se proteger contra a perda acidental de dados.

Familiarize-se com a verificação de site

Se você não conhece os conceitos da API Google Site Verification, leia este documento, teste a interface do usuário de verificação e leia a documentação de ajuda associada antes de começar a programar.

Saiba como autorizar solicitações

Toda solicitação que seu aplicativo envia para a API Google Site Verification precisa incluir um token de autorização. O token também identifica o aplicativo para o Google.

Sobre os protocolos de autorização

O aplicativo deve obrigatoriamente usar o OAuth 2.0 para autorizar solicitações. Não há outros protocolos de autorização compatíveis. Se o aplicativo usa o Fazer login com o Google, alguns aspectos da autorização são administrados para você.

Autorizar solicitações com OAuth 2.0

Todas as solicitações para a API Google Site Verification precisam ser autorizadas por um usuário autenticado.

Os detalhes do processo de autorização ou “fluxo” para o OAuth 2.0 variam um pouco, dependendo do tipo de aplicativo que você está criando. O processo geral a seguir se aplica a todos os tipos de aplicativo:

  1. Ao criar seu aplicativo, registre-o usando o Console de APIs do Google. Em seguida, o Google fornece informações que serão usadas mais tarde, como um ID e uma chave secreta do cliente.
  2. Ative a API Google Site Verification no Console de APIs do Google. Se ela não estiver no Console de APIs, pule essa etapa.
  3. Quando seu aplicativo precisar de acesso aos dados do usuário, ele solicitará ao Google um determinado escopo do acesso.
  4. O Google exibe uma tela de consentimento ao usuário, pedindo para que o aplicativo seja autorizado a solicitar alguns dos dados dele.
  5. Se o usuário aprovar, o Google fornecerá ao aplicativo um token de acesso de curta duração.
  6. O aplicativo solicita dados de usuário, anexando o token de acesso à solicitação.
  7. Se o Google determinar que a solicitação e o token são válidos, ele retornará os dados solicitados.

Alguns fluxos incluem etapas adicionais, como atualizar tokens para adquirir novos tokens de acesso. Para mais informações sobre fluxos de vários tipos de aplicativos, acesse a documentação OAuth 2.0 do Google.

Veja as informações de escopo do OAuth 2.0 para a API Google Site Verification:

Escopo Significado
https://www.googleapis.com/auth/siteverification Acesso total de leitura para sites verificados existentes e capacidade de verificar novos sites.
https://www.googleapis.com/auth/siteverification.verify_only Capacidade de verificar novos sites, sem acesso de leitura para sites verificados existentes.

Para solicitar acesso usando o OAuth 2.0, seu aplicativo precisa de informações do escopo, bem como informações fornecidas pelo Google durante o registro do aplicativo, como o ID e a chave secreta do cliente.

Dica: as bibliotecas cliente de APIs do Google cuidam de parte do processo de autorização para você. Elas estão disponíveis para uma série de linguagens de programação. Acesse a página de bibliotecas e exemplos para mais detalhes.

Experiência na API Google Site Verification

Conceitos

Você pode usar a API Google Site Verification para estabelecer a propriedade de um usuário para os seguintes tipos de recursos da Web:

  • Domínio:um domínio ou subdomínio. O proprietário de um domínio é considerado proprietário de todos os sites e subdomínios sob esse domínio. Por exemplo, o proprietário direto de bar.com também é considerado o proprietário indireto de foo.bar.com.
  • Site:um URL correspondente ao domínio de base e ao caminho de um site. O proprietário de um site é considerado o proprietário de todos os sites dele. Por exemplo, o proprietário de "http://www.example.com/site" também é considerado o proprietário de "http://www.example.com/site/subsite".

Como a propriedade do domínio é mais amplamente aplicável do que a propriedade do site, recomendamos que você faça a verificação com os domínios sempre que possível.

O processo de estabelecimento da propriedade começa quando seu aplicativo solicita um "token de verificação" em nome do usuário. O token de verificação é uma string especial que seu código precisa colocar no site ou domínio. Depois que o token estiver no lugar, seu aplicativo poderá fazer uma solicitação à API Google Site Verification, que verifica o token e registra a propriedade quando ele é encontrado.

Limitações

Por motivos técnicos e de segurança, a API Google Site Verification impõe algumas restrições sobre o uso dela:

  • Acesso a dados somente para usuários autenticados: todas as operações exigem autenticação e autorização do usuário.
  • Verificação somente para usuário autenticado: a API só pode verificar a propriedade de sites ou domínios da conta autenticada no momento. No entanto, o usuário autenticado pode delegar a propriedade a outros usuários após a confirmação da propriedade de um site. Todos os proprietários são notificados por e-mail sempre que são feitas alterações na lista de propriedade.
  • Somente URLs normalizados e nomes de domínio. A API de verificação de sites do Google não suporta a codificação IDN (Nome de domínio internacional). Certifique-se de normalizar todos os URLs, nomes de domínio e domínios de endereços de e-mail para o conjunto de caracteres de nome de domínio padrão (RFC 1034 §3.5) usando Punyencoding, se necessário.

Métodos e tokens de verificação

A API fornece chamadas para as fases separadas da verificação:

  • Inserir o token de verificação: há uma chamada de API para recuperar um token de verificação a ser colocado no site do usuário autenticado. Se um usuário tiver mais de um site, você vai precisar de um token diferente para cada um deles.
  • Verificação da presença do token de verificação: há uma chamada de API separada para solicitar que o Google verifique o token com o objetivo de confirmar se o usuário autenticado é o proprietário de um site.

Há vários métodos para verificar um site ou domínio que seu aplicativo pode usar: a seleção depende do que funciona melhor para suas necessidades. O local onde o token deve ser colocado e o tipo dele dependem do método de verificação escolhido.

Método de verificação de domínio

Há dois métodos de verificação disponíveis para domínios:

DNS_CNAME

Seu aplicativo cria um novo registro CNAME para o domínio do proprietário, possivelmente por meio do registro de domínios, usando o token para os dados de registro. O token é composto por duas partes separadas por um espaço: a primeira parte é o nome do novo registro CNAME, a segunda parte é o valor do novo registro CNAME.

DNS_TXT

Seu aplicativo cria um novo registro TXT para o domínio do proprietário, possivelmente por meio do registrador de domínios, usando o token para os dados de registro.

Consulte a documentação da Central de Ajuda sobre o método de verificação de DNS para mais informações.

Métodos de verificação de site

Três métodos de verificação estão disponíveis para sites:

Arquivo
Seu aplicativo coloca o token, na forma de um arquivo, no site do proprietário. Você deve criar um arquivo, nomeado para corresponder à string do token, com o seguinte conteúdo: 
google-site-verification: token

Por exemplo, se um usuário for proprietário do site http://www.example.com/ e o token retornado for google12cfc68677988bb4.html, você só precisará criar um arquivo em http://www.example.com/google12cfc68677988bb4.html (no nível superior do site), com este conteúdo:

google-site-verification: google12cfc8677988bb4.html

Para mais informações, consulte a documentação da Central de Ajuda sobre o método de verificação de arquivo.

Meta

Seu aplicativo insere o token, na forma de uma tag HTML <meta>, no elemento <head> do arquivo padrão (index.html, default.html etc.) no nível superior do site do proprietário. Um arquivo HTML com um token de verificação Meta pode ter a seguinte aparência:

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

Consulte a documentação da Central de Ajuda sobre o Método de verificação meta para mais informações.

Analytics

Seu aplicativo usa um código de acompanhamento do Google Analytics que já está no site do proprietário. O código de acompanhamento precisa pertencer à conta do Google Analytics do usuário, e o snippet precisa estar localizado na tag HEAD para funcionar. Consulte a documentação da Central de Ajuda sobre o método de verificação do Google Analytics para mais informações.

Gerenciador de tags

Seu aplicativo usa um código de contêiner do Gerenciador de tags do Google que já está no site do proprietário. O código do contêiner precisa pertencer à conta do Gerenciador de tags. Consulte a documentação da Central de Ajuda sobre o método de verificação do Gerenciador de tags para mais informações.

Ele poderá ser útil para sua compreensão dos principais conceitos e fluxo de trabalho se você tentar verificar alguns sites manualmente com a interface do usuário da Verificação de sites.

Modelo de dados

Recurso da Web

A API Google Site Verification aplica a semântica REST (HTTP GET, POST etc.) a entidades chamadas de recursos da Web. Um recurso da Web é um site ou domínio que pertence ao usuário autenticado.

Aqui está um exemplo de um recurso da Web:

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

O campo id é um identificador exclusivo para esse recurso da Web. Use-o para fazer referência a esse recurso da Web específico para recuperação e modificação. Armazene o campo id da saída da operação list para usar depois como identificador.

O objeto site contém o URL ou o nome de domínio do recurso da Web e o tipo do recurso. Os sites são especificados com o tipo SITE. são especificados com o tipo INET_DOMAIN.

A matriz owners é a lista completa de proprietários do recurso da Web, representada pelos endereços de e-mail deles. Ao adicionar ou remover endereços de e-mail da lista de proprietários, o usuário autenticado pode conceder propriedade conjunta ou revogar a propriedade de outros usuários. Proprietários adicionais que colocaram seus próprios tokens no site ou domínio também aparecerão na lista de proprietários, junto com seus co-proprietários.

Os usuários que receberam a copropriedade também podem concedê-la, desde que haja pelo menos um proprietário verificado com um token no site.

Coleção de recursos da Web

A coleção de recursos da Web é uma lista completa de todos os recursos da Web que pertencem ao usuário autenticado. Você pode confirmar a propriedade de sites ou domínios simplesmente tentando adicionar novos recursos da Web ao conjunto de recursos da Web do usuário autenticado. Somente sites ou domínios verificados foram adicionados à coleção.

Como informado na seção Limitações, os recursos da Web que pertencem a outros usuários não podem ser acessados pela API Site Verification.