Per iniziare

Questo documento descrive in dettaglio le conoscenze di base necessarie per utilizzare l'API Google Site Verification.

Introduzione

L'API Google Site Verification è destinata agli sviluppatori che vogliono scrivere applicazioni o servizi che automatizzare il processo di verifica della proprietà di un sito o di un dominio. Questo è importante, dato che I servizi Google possono essere utilizzati solo dai proprietari di siti web o domini. Puoi utilizzare l'API Google Site Verification per verificare che l'utente autenticato sia il proprietario del dominio o del sito, possibilmente come primo il provisioning di altri servizi Google in modo programmatico.

In questo documento si presuppone che tu abbia familiarità con i concetti di programmazione web, i formati di dati web e di avere la possibilità di modificare in modo programmatico i file o i record DNS del sito web o del dominio.

Panoramica

Puoi utilizzare l'API Google Site Verification per modificare i dati relativi alla verifica del sito Google di un utente. Gli utenti possono solo accedere a determinati servizi Google se i dati di verifica indicano che sono proprietari dei specifico dominio di un sito web. Puoi utilizzare l'API per generare token di verifica per utenti, che il tuo codice può inserire in vari modi nei tuoi siti web o record di dominio nei loro per conto tuo. Una volta che il token è a disposizione, effettui una chiamata all'API per chiedere a Google di verificare di accesso. Se Google trova il token, registra l'utente autenticato come proprietario del sito web o un dominio. L'API può essere utilizzata anche per modificare l'elenco di proprietà per conto dell'utente oppure per rimuovere completamente la proprietà del sito.

Tutte le chiamate API devono essere autorizzate da un utente autenticato e tutte le chiamate API vengono eseguite nel contesto dell'account dell'utente autenticato.

Supponiamo che tu fornisca un servizio di hosting web, ad esempio quando potresti utilizzare questa API. I tuoi utenti vogliono poter utilizzare Search Console di Google per ottenere informazioni sul proprio sito. Per fare ciò, Google deve sapere che non lo possiedono. Offrite agli utenti un'interfaccia che li invita a verificare proprietà del sito. L'utente concede alla tua applicazione l'accesso ai propri dati di verifica e può ora eseguire codice che richiede un token per loro conto e inserirlo in un file sul proprio sito della struttura e chiede a Google di verificarla. Quando Google trova il token, ne concede la proprietà il sito all'utente aggiornando i suoi dati di verifica. Ora può usare Search Console per ottenere le informazioni che desiderano.

Prima di iniziare

Come procurarsi un account Google

Assicurati di avere configurato un Account Google. Per proteggerti dalla perdita accidentale di dati, ti consigliamo di utilizzare un Account Google separato a scopo di sviluppo e test.

Acquisisci familiarità con la verifica del sito

Se non hai dimestichezza con i concetti dell'API Google Site Verification, prima di iniziare a programmare, devi leggere questo documento, provare l'interfaccia utente di verifica e leggere la documentazione di assistenza associata.

Scopri come autorizzare le richieste

Ogni richiesta inviata dalla tua applicazione all'API Google Site Verification deve includere un token di autorizzazione. Il token, inoltre, identifica l'applicazione per Google.

Informazioni sui protocolli di autorizzazione

La tua applicazione deve utilizzare il protocollo OAuth 2.0 per autorizzare le richieste. Non sono supportati altri protocolli di autorizzazione. Se la tua applicazione utilizza la funzionalità Accedi con Google, alcuni aspetti dell'autorizzazione vengono gestiti per te.

Autorizzazione delle richieste con OAuth 2.0

Tutte le richieste all'API Google Site Verification devono essere autorizzate da un utente autenticato.

I dettagli della procedura di autorizzazione, o "flusso", per il protocollo OAuth 2.0 variano a seconda del tipo di applicazione che stai scrivendo. La seguente procedura generale si applica a tutti i tipi di applicazione:

  1. Quando crei la tua applicazione, la registri utilizzando la console API di Google. Quindi, Google fornisce informazioni che ti saranno necessarie in un secondo momento, ad esempio un ID client e un client secret.
  2. Attiva l'API Google Site Verification nella console API di Google. (Se l'API non è elencata nella console API, salta questo passaggio.)
  3. Quando la tua applicazione vuole accedere ai dati dell'utente, chiede a Google un particolare ambito di accesso.
  4. Google mostra una schermata di consenso all'utente, chiedendo di autorizzare l'applicazione a richiedere dei dati.
  5. Se l'utente approva, Google fornisce alla tua applicazione un token di accesso di breve durata.
  6. L'applicazione richiede i dati utente, allegando il token di accesso alla richiesta.
  7. Se Google ritiene validi la richiesta e il token, restituisce i dati richiesti.

Alcuni flussi includono passaggi aggiuntivi, come l'uso di token di aggiornamento per acquisire nuovi token di accesso. Per informazioni dettagliate sui flussi per vari tipi di applicazioni, consulta la documentazione relativa al protocollo OAuth 2.0 di Google.

Ecco le informazioni relative all'ambito OAuth 2.0 per l'API Google Site Verification:

Ambito Significato
https://www.googleapis.com/auth/siteverification Accesso completo in lettura per i siti verificati esistenti, possibilità di verificare i nuovi siti.
https://www.googleapis.com/auth/siteverification.verify_only Possibilità di verificare i nuovi siti, nessun accesso in lettura per i siti verificati esistenti.

Per richiedere l'accesso utilizzando il protocollo OAuth 2.0, l'applicazione richiede le informazioni relative all'ambito e le informazioni che Google fornisce quando registri la tua applicazione (ad esempio l'ID client e il client secret).

Suggerimento: le librerie client delle API di Google possono gestire parte del processo di autorizzazione per te. Sono disponibili per una varietà di linguaggi di programmazione; consulta la pagina delle librerie e dei campioni per maggiori dettagli.

Informazioni di base sull'API Google Site Verification

Concetti

Puoi utilizzare l'API Google Site Verification per stabilire la proprietà da parte di un utente dei seguenti tipi di risorse web:

  • Dominio: un dominio o un sottodominio. Il proprietario di un dominio è considerato proprietario di tutti i siti e sottodomini di quel dominio. Ad esempio, il proprietario diretto di bar.com è considerato anche il proprietario indiretto di foo.bar.com.
  • Sito: un URL corrispondente al dominio di base e al percorso di un sito web. Il proprietario di un sito è considerato il proprietario di tutti i siti secondari. Ad esempio, anche il proprietario di "http://www.example.com/site" è considerato il proprietario di "http://www.example.com/site/subsite".

Poiché la proprietà del dominio è applicabile in modo più ampio rispetto alla proprietà del sito, ti consigliamo di eseguire la verifica con i domini, ove possibile.

Il processo per stabilire la proprietà inizia con la richiesta da parte della tua applicazione di un "token di verifica" per conto dell'utente. Il token di verifica è una stringa speciale che il tuo codice deve poi inserire nel sito web o nel dominio dell'utente. Una volta creato il token, la tua richiesta può inviare una richiesta all'API Google Site Verification, che controlla il token e registra la proprietà quando viene trovato.

Limitazioni

Per motivi tecnici e di sicurezza, l'API Google Site Verification applica alcune limitazioni al suo utilizzo:

  • Accesso ai dati solo per utenti autenticati : tutte le operazioni richiedono l'autenticazione e l'autorizzazione dell'utente.
  • Verifica solo per utenti autenticati:l'API può verificare la proprietà dei siti o dei domini soltanto per l'account attualmente autenticato. Tuttavia, l'utente autenticato può delegare la proprietà ad altri utenti una volta verificata la proprietà di un sito. Tieni presente che tutti i proprietari ricevono una notifica via email ogni volta che vengono apportate modifiche all'elenco di proprietà.
  • Solo URL e nomi di dominio normalizzati. L'API Google Site Verification non supporta la codifica IDN (International Domain Name). Accertati di normalizzare tutti gli URL, i nomi di dominio e i domini degli indirizzi email in base al set di caratteri dei nomi di dominio standard (RFC 1034 §3.5) utilizzando Punycoding, se necessario.

Metodi di verifica e token

L'API fornisce chiamate per le diverse fasi della verifica:

  • Inserimento del token di verifica : viene avviata una chiamata API per il recupero di un token di verifica da inserire sul sito dell'utente autenticato. Se un utente ha più di un sito, è necessario ottenere un token diverso per ogni sito.
  • Controllo della presenza del token di verifica : esiste una chiamata API separata per richiedere a Google il controllo del token per verificare che l'utente autenticato sia proprietario di un sito.

Esistono diversi metodi per verificare un sito web o un dominio utilizzabile dalla tua applicazione. quella che selezioni dipende da ciò che funziona meglio per le tue esigenze. La posizione del token e il tipo di token stesso dipendono dal metodo di verifica scelto.

Metodo di verifica del dominio

Sono disponibili due metodi di verifica per i domini:

DNS_CNAME

L'applicazione crea un nuovo record CNAME per il dominio del proprietario, probabilmente tramite il registrar del dominio, utilizzando il token per i dati del record. Il token è composto da due parti separate da uno spazio: la prima è il nome del nuovo record CNAME, la seconda il valore del nuovo record CNAME.

DNS_TXT

L'applicazione crea un nuovo record TXT per il dominio del proprietario, possibilmente tramite il registrar del dominio, utilizzando il token per i dati del record.

Per ulteriori informazioni, consulta la documentazione del Centro assistenza sul metodo di verifica DNS.

Metodi di verifica del sito

Sono disponibili tre metodi di verifica per i siti:

File
La tua applicazione inserisce il token, sotto forma di file, nel sito web del proprietario. Devi creare un file, denominato in modo che corrisponda alla stringa del token, con il seguente contenuto: 
google-site-verification: token

Ad esempio, se un utente è proprietario del sito http://www.example.com/ e il token restituito è google12cfc68677988bb4.html, devi semplicemente creare un file all'indirizzo http://www.example.com/google12cfc68677988bb4.html (al livello superiore del sito), con il seguente contenuto:

google-site-verification: google12cfc8677988bb4.html

Per ulteriori informazioni, consulta la documentazione del Centro assistenza sul metodo di verifica dei file.

Meta

L'applicazione inserisce il token, sotto forma di tag HTML <meta>, all'interno dell'elemento <head> del file predefinito (index.html, default.html e così via) nel livello superiore del sito del proprietario. Un file HTML con un token di meta verifica potrebbe avere il seguente aspetto:

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

Per ulteriori informazioni, consulta la documentazione del Centro assistenza sul metodo di verifica dei metadati.

Analytics

L'applicazione utilizza un codice di monitoraggio di Google Analytics esistente già presente sul sito web del proprietario. Per funzionare, il codice di monitoraggio deve appartenere all'account Analytics e lo snippet deve trovarsi nel tag HEAD. Per saperne di più, consulta la documentazione del Centro assistenza sul metodo di verifica di Analytics.

Tag Manager

La tua applicazione utilizza un codice contenitore Google Tag Manager esistente già presente sul sito web del proprietario. Il codice del contenitore deve appartenere all'account Tag Manager. Per saperne di più, consulta la documentazione del Centro assistenza sul metodo di verifica di Tag Manager.

Può essere utile per comprendere i concetti principali e il flusso di lavoro se provi prima a verificare manualmente alcuni siti con l'interfaccia utente di Site Verification.

Modello dei dati

Risorsa web

L'API Google Site Verification applica la semantica REST (HTTP GET, POST e così via) alle entità chiamate risorse web. Una risorsa web è un sito web o un dominio che appartiene all'utente autenticato.

Ecco un esempio di risorsa web:

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

Il campo id è un identificatore univoco per questa risorsa web. Puoi utilizzarlo per fare riferimento a questa particolare risorsa web per il recupero e la modifica. Archivia il campo id dall'output dell'operazione list per utilizzarlo in un secondo momento come identificatore.

L'oggetto site contiene l'URL o il nome di dominio della risorsa web e il tipo di risorsa. I siti vengono specificati con il tipo SITE; domini sono specificati con il tipo INET_DOMAIN.

L'array owners è l'elenco completo dei proprietari della risorsa web, rappresentati dai loro indirizzi email. Aggiungendo o rimuovendo indirizzi email dall'elenco dei proprietari, l'utente autenticato può concedere la comproprietà o revocare la proprietà per altri utenti. Nell'elenco dei proprietari vengono visualizzati anche altri proprietari che hanno inserito token propri sul sito o nel dominio, insieme ai rispettivi comproprietari.

Gli utenti a cui è stata concessa la comproprietà possono anche concedere la comproprietà, purché sul sito sia presente almeno un proprietario verificato con un token.

Raccolta di risorse web

La raccolta di risorse web è un elenco completo di tutte le risorse web che appartengono all'utente autenticato. Puoi verificare la proprietà di siti o domini semplicemente tentando di aggiungere nuove risorse web alla raccolta di risorse web dell'utente autenticato. Solo i siti o i domini verificati vengono aggiunti alla loro raccolta.

Come indicato in precedenza nella sezione Limitazioni, le risorse web che appartengono a utenti diversi dall'utente autenticato non sono accessibili tramite l'API Site Verification.