Vamos começar

Este documento detalha o conhecimento histórico necessário para usar a API Google Site Verification.

Introdução

A API Google Site Verification é destinada a desenvolvedores que querem criar aplicativos ou serviços que automatizem o processo de verificação de propriedade de um site ou domínio. Isso é importante porque alguns Serviços do Google só podem ser usados por proprietários de sites ou domínios. Você pode usar a API Google Site Verification para validar se o usuário autenticado é proprietário do domínio ou do site, possivelmente como a primeira etapa no provisionamento de outros serviços do Google de forma programática.

Ele pressupõe que você está familiarizado com conceitos de programação e formatos de dados da Web, além de poder modificar de maneira programática os arquivos ou registros DNS do seu site ou domínio.

Visão geral

Você pode usar a API Google Site Verification para modificar os dados de verificação do site do Google de um usuário. Os usuários só poderão acessar determinados Serviços do Google se os dados de verificação mostrarem que eles são os proprietários do domínio do site específico. É possível usar a API a fim de gerar tokens de verificação para usuários autenticados, que o código pode colocar de várias maneiras nos seus sites ou registros de domínio em nome deles. Quando o token estiver configurado, faça uma chamada à API para solicitar ao Google a verificação do token. Se o Google encontrar o token, ele registrará o usuário autenticado como proprietário do site ou domínio. Você também pode usar a API para modificar a lista de propriedade em nome do usuário ou para remover a propriedade do site por completo.

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.

Um exemplo concreto de quando você pode usar essa API: suponha que você ofereça um serviço de hospedagem na Web. Seus usuários querem poder usar o Search Console do Google para receber informações sobre o site. Para que isso seja possível, o Google precisa saber que a propriedade é realmente sua. Portanto, você oferece aos usuários uma interface que solicita a verificação da propriedade do site. Eles dão ao aplicativo acesso aos dados de verificação. Além disso, ele pode executar códigos que solicitam um token em nome deles, coloca-o em um arquivo na estrutura do site e pede ao Google para verificá-lo. Ao encontrar o token, o Google concede a propriedade do site ao usuário atualizando os dados de verificação. Agora é possível usar o Search Console para receber as informações desejadas.

Antes de começar

Criar uma Conta do Google

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

Conhecer a verificação de site

Se você não tiver familiaridade com 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

Todas as solicitações que seu aplicativo envia para a API Google Site Verification precisam 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á mais 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 à 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 ver informações detalhadas sobre fluxos de vários tipos de aplicativos, consulte a documentação do OAuth 2.0 do Google.

Estas são as informações de escopo do OAuth 2.0 para a API Google Site Verification:

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

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.

Contexto da API Google Site Verification

conceitos

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

  • Domínio:é um domínio ou subdomínio. O proprietário de um domínio é considerado o proprietário de todos os sites e subdomínios desse 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 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 abrangente que a propriedade do site, recomendamos que você verifique os domínios sempre que possível.

Para estabelecer a propriedade, o aplicativo precisa solicitar 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 dele. Depois que o token é definido, seu aplicativo pode 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 aplica algumas restrições ao uso:

  • Acesso de dados somente para usuários autenticados: todas as operações exigem autenticação e autorização do usuário.
  • Verificação apenas para usuário autenticado:a API só verifica a propriedade de sites ou domínios da conta autenticada. No entanto, o usuário autenticado poderá delegar a propriedade a outros usuários após a verificaçã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 proprietários.
  • Somente URLs normalizados e nomes de domínio. A API Google Site Verification não é compatível com a codificação IDN (International Domain Name). Normalize todos os URLs, nomes de domínio e domínios de endereço de e-mail no conjunto de caracteres padrão de nome de domínio (RFC 1034 §3.5) usando Punycode, se necessário.

Métodos e tokens de verificação

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

  • Colocar 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ê precisará gerar um token diferente para cada site.
  • Verificar a presença do token de verificação: há uma chamada de API separada para solicitar que o Google verifique o token para verificar se o usuário autenticado é proprietário de um site.

Há vários métodos para verificar um site ou domínio que o aplicativo pode usar. O que você escolhe depende do que funciona melhor para seus requisitos. O posicionamento do token 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

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

DNS_TXT

O seu aplicativo cria um novo registro TXT para o domínio do proprietário, possivelmente por meio do seu registrador, usando o token para os dados do 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 do 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ê precisa criar um arquivo nomeado para a string do token com o seguinte conteúdo: 
google-site-verification: token

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

google-site-verification: google12cfc8677988bb4.html

Veja mais informações na documentação da Central de Ajuda sobre o método de verificação de arquivo.

Meta

O aplicativo insere o token, na forma de uma tag <meta> HTML, 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.

Análise

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, 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 do 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 dele. Consulte a documentação da Central de Ajuda sobre o método de verificação do Gerenciador de tags para mais informações.

Isso é útil para sua compreensão dos principais conceitos e do fluxo de trabalho na primeira tentativa de verificar alguns sites manualmente com a interface do usuário da Verificação de site.

Modelo de dados

Recurso da Web

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

Veja um exemplo de 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 desse recurso da Web. Ele é usado para referenciar esse recurso da Web específico para recuperação e modificação. Armazene o campo id da saída da operação list para uso posterior como identificador.

O objeto site contém o URL ou nome de domínio do recurso da Web e o tipo do recurso. Os sites são especificados com o tipo SITE. Os domínios 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. Ao adicionar ou remover endereços de e-mail da lista de proprietários, o usuário autenticado pode conceder a copropriedade ou revogar a propriedade de outros usuários. Os proprietários adicionais que colocaram tokens próprios no site ou domínio também aparecem na lista de proprietários, incluindo qualquer um dos coproprietários.

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

Coleta 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 verificar a propriedade de sites ou domínios simplesmente tentando adicionar novos recursos da Web ao conjunto de recursos da Web do usuário autenticado. Apenas sites ou domínios verificados são adicionados à coleção.

Conforme mencionado anteriormente na seção Limitações, os recursos da Web que pertencem a usuários que não sejam o usuário autenticado não podem ser acessados pela API Site Verification.