Per iniziare

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

Introduzione

L'API Google Site Verification è rivolta agli sviluppatori che vogliono scrivere applicazioni o servizi che automatizzano il processo di verifica della proprietà di un sito o un dominio. Questo è importante perché alcuni servizi Google possono essere utilizzati solo dai proprietari di siti web o domini. Puoi utilizzare l'API Google Site Verification per convalidare che l'utente autenticato è un proprietario del dominio o del sito. Forse il primo passaggio consiste nel eseguire in modo programmatico il provisioning di altri servizi Google.

Questo documento presuppone che tu abbia familiarità con i concetti di programmazione web e i formati dei dati web e che tu sia in grado di modificare in modo programmatico i file o i record DNS del tuo sito web o dominio.

Panoramica

Puoi utilizzare l'API Google Site Verification per modificare i dati di verifica del sito Google di un utente. Gli utenti possono accedere a determinati servizi Google solo se i loro dati di verifica dimostrano che sono proprietari del dominio del sito web in particolare. Puoi utilizzare l'API per generare token di verifica per gli utenti autenticati, che il tuo codice può inserire in diversi modi sui tuoi siti web o nei record di dominio per loro conto. Dopo aver individuato il token, chiama l'API per chiedere a Google di cercarlo. Se Google trova il token, registra l'utente autenticato come proprietario del sito web o del dominio. Puoi anche utilizzare l'API per modificare l'elenco delle proprietà per conto dell'utente o per rimuovere del tutto 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.

Come esempio concreto di quando potresti utilizzare questa API, supponiamo che tu fornisca un servizio di hosting web. I tuoi utenti vogliono essere in grado di utilizzare la Search Console di Google per ottenere informazioni sul loro sito. Perché possa farlo, Google deve sapere che è di sua proprietà. In questo modo fornisci agli utenti un'interfaccia che chiede di verificare la loro proprietà del sito. Consentono all'applicazione di accedere ai propri dati di verifica e ora può eseguire il codice che richiede un token per loro conto, inserirlo in un file nella struttura del proprio sito e chiedere a Google di controllarlo. Quando Google trova il token, concede la proprietà del sito all'utente aggiornando i suoi dati di verifica. Ora può utilizzare Search Console per ottenere le informazioni di cui ha bisogno.

Prima di iniziare

Crea un account Google

Assicurati di avere configurato un Account Google. Consigliamo di utilizzare un Account Google separato per scopi di sviluppo e test in modo da proteggersi da perdite accidentali dei dati.

Acquisisci familiarità con la verifica del sito

Se non hai familiarità con i concetti dell'API Google Site Verification, ti consigliamo di leggere questo documento, fare esperimenti con l'interfaccia utente di verifica e leggere la documentazione di assistenza associata prima di iniziare la programmazione.

Scopri come autorizzare le richieste

Ogni richiesta che la tua applicazione invia 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 Accedi con Google, alcuni aspetti dell'autorizzazione vengono gestiti automaticamente.

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 sull'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, senza 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.

Sfondo dell'API Google Site Verification

Concetti

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

  • Dominio: un dominio o un sottodominio. Il proprietario di un dominio è considerato il proprietario di tutti i siti e sottodomini di tale 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 al suo interno. Ad esempio, il proprietario di "http://www.example.com/site" è anche considerato il proprietario di "http://www.example.com/site/subsite".

Poiché la proprietà del dominio è più ampiamente applicabile rispetto alla proprietà del sito, ti consigliamo di eseguire la verifica con i domini ogni volta che è possibile.

Il processo di definizione della proprietà inizia con l'applicazione che richiede un "token di verifica" per conto dell'utente. Il token di verifica è una stringa speciale che il codice deve inserire sul sito web o nel dominio. Dopo che il token è attivo, la tua applicazione può inviare una richiesta all'API Google Site Verification che controlla il token e ne registra la proprietà quando viene rilevato.

Limitazioni

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

  • Accesso ai dati solo per utente autenticato: tutte le operazioni richiedono l'autenticazione e l'autorizzazione dell'utente.
  • Verifica solo per utenti autenticati: l'API può verificare solo la proprietà dei siti o dei domini per l'account attualmente autenticato. Tuttavia, l'utente autenticato può delegare la proprietà ad altri utenti dopo che la proprietà di un sito è stata verificata. 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). Assicurati di normalizzare tutti gli URL, i nomi di dominio e i domini degli indirizzi email con il set di caratteri dei nomi di dominio standard (RFC 1034 §3.5) utilizzando Punycoding, se necessario.

Metodi e token di verifica

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

  • Inserimento del token di verifica. È presente una chiamata API per recuperare un token di verifica da inserire sul sito dell'utente autenticato. Se un utente ha più di un sito, devi ottenere un token diverso per ogni sito.
  • Controllare la presenza del token di verifica: esiste una chiamata API separata per richiedere a Google di verificare il token per verificare che l'utente autenticato sia proprietario di un sito.

Esistono diversi metodi per verificare un sito web o un dominio che l'applicazione può utilizzare. Quello selezionato dipende da ciò che funziona meglio per i tuoi requisiti. La posizione del token e il tipo di token dipendono dal metodo di verifica scelto.

Metodo di verifica del dominio

Esistono due metodi di verifica disponibili per i domini:

DNS_CNAME

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

TXT_DNS

L'applicazione crea un nuovo record TXT per il dominio del proprietario, eventualmente tramite il suo registrar di domini, 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 dei siti:

File
La tua applicazione posiziona il token, sotto forma di file, sul sito web del proprietario. Devi creare un file denominato in modo che corrisponda alla stringa 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, dovrai semplicemente creare un file all'indirizzo http://www.example.com/google12cfc68677988bb4.html (al livello più alto del suo sito), con i seguenti contenuti:

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) al livello superiore del sito del proprietario. Un file HTML con un token di verifica della meta 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 tramite Meta.

Analisi

La tua applicazione utilizza un codice di monitoraggio di Google Analytics esistente già sul sito web del proprietario. Il codice di monitoraggio deve appartenere al suo account Analytics e lo snippet deve essere posizionato nel tag HEAD per funzionare. Per scoprire 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à sul sito web del proprietario. Il codice contenitore deve appartenere al suo account Tag Manager. Per ulteriori informazioni, consulta la documentazione del Centro assistenza sul metodo di verifica di Tag Manager.

Può essere utile per capire i concetti principali e il flusso di lavoro se provi a verificare manualmente alcuni siti con l'interfaccia utente di Verifica del sito.

Modello dei dati

Risorsa web

L'API Google Site Verification applica la semantica REST (HTTP GET, POST ecc.) a 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. Lo utilizzi per fare riferimento a questa particolare risorsa web per il recupero e la modifica. Memorizza il campo id nell'output dell'operazione list per utilizzarlo in seguito 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; i domini sono specificati con il tipo INET_DOMAIN.

L'array owners è l'elenco completo dei proprietari della risorsa web, rappresentato dai loro indirizzi email. Aggiungendo o rimuovendo indirizzi dall'elenco dei proprietari, l'utente autenticato può concedere la proprietà condivisa o revocare la proprietà per altri utenti. Anche i proprietari aggiuntivi che hanno inserito token propri nel sito o nel dominio vengono visualizzati nell'elenco dei proprietari, insieme ai relativi comproprietari.

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

Raccolta risorse web

La raccolta di risorse web è un elenco completo di tutte le risorse web che appartengono all'utente autenticato. Puoi verificare la proprietà dei siti o dei domini semplicemente provando ad 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.