Panoramica sull'integrazione

Annunci di Servizi locali (LSA) per collaborare con gli aggregatori per mostrare i loro elenchi (o fornitori) su Google.com. In questa guida viene descritto come gli aggregatori possono fornire dati strutturati LSA sui loro fornitori. Nello specifico, documentiamo l'insieme di endpoint API che gli aggregatori devono implementare per l'integrazione con gli annunci di Servizi locali.

Glossario

Aggregatore (o partner): si tratta di partner che aggregano i fornitori a cui forniscono servizi e i cui dati possono essere forniti agli annunci di Servizi locali.

Fornitore (o scheda) di terze parti: si tratta di singole piccole attività (ad es. Joe's plumbing) che potrebbero avere un rapporto commerciale con gli aggregatori. Gli aggregatori forniscono a Servizi locali informazioni su queste attività.

Panoramica

Gli aggregatori forniranno a Servizi locali i dati sui loro fornitori (attività) utilizzando i feed. Ogni feed è costituito da dati relativi a più fornitori. All'interno di un feed, i dati relativi a un singolo fornitore sono incapsulati da un elemento del feed. Ogni feed specifica anche un timestamp che indica la freschezza del feed. Ogni feed specifica anche un tipo di feed: possono essere dati sul profilo del fornitore o recensioni del fornitore, come descritto di seguito.

Tipi di feed

Per l'integrazione iniziale, ogni feed può essere uno dei seguenti tipi:

  • Feed dei profili: questo feed fornisce informazioni sui profili dei fornitori. Ogni elemento del feed contiene informazioni sul profilo di un determinato fornitore. Sono inclusi un ID attività univoco, il nome dell'attività, le sedi di pubblicazione, i servizi offerti, l'orario di apertura e così via. L'elemento del feed contiene anche i metadati di pubblicazione per questa attività (ad es. l'importo del budget mensile, lo stato dell'annuncio e così via).

  • Feed recensioni: questo feed fornisce informazioni sulle recensioni dei fornitori. Ogni elemento del feed contiene un elenco di recensioni dettagliate dei consumatori di un determinato fornitore. Ogni recensione dei consumatori è composta da nome, valutazione (da 1 a 5), testo, timestamp e così via.

Per ulteriori dettagli sui campi specifici e sulla loro semantica, consulta Feed del profilo e Feed delle recensioni.

Importazione del feed

I dati del feed vengono serializzati come JSON. Per inviare i dati, LSA supporterà solo un meccanismo pull. In futuro è prevista l'implementazione di un meccanismo push.

Meccanismo di pull

Nel meccanismo pull, gli aggregatori supportano un insieme di endpoint REST predefiniti (URL) che inviano e ricevono oggetti JSON. È analogo all'hosting di uno o più file su un server web. LSA invierà periodicamente richieste HTTP GET a questi URL per recuperare i dati. I dettagli sugli URL predefiniti sono disponibili nella sezione successiva sugli endpoint API.

Meccanismo push

Nel meccanismo push, LSA fornirà un endpoint che gli aggregatori potranno chiamare e fornire dati. A livello semantico, è uguale a un pull, ma offre flessibilità nei casi in cui gli aggregatori vogliono inviare dati specifici a Servizi locali. Tutte le semantiche, le regole o i vincoli descritti nel protocollo si applicano sia al push che al pull nello stesso modo.

Endpoint API

I seguenti endpoint devono essere supportati dagli aggregatori: uno per il feed del profilo e uno per il feed delle recensioni.

Ti consigliamo di includere informazioni sulla versione negli endpoint, come indicato di seguito. Iniziamo con v1.

Endpoint Percorso
Feed del profilo /feeds/{version}/profile
Feed delle recensioni /feeds/{version}/review

Parametro endpoint

Parametri Descrizione
maxresults Questo è il limite al numero di elementi del feed che possono essere richiesti in una pagina.
nextpagetoken Token di paginazione per ottenere la pagina successiva dei risultati

Autenticazione endpoint

L'autenticazione utilizza l'autenticazione di base HTTP: nome utente e password con codifica base64 per l'autenticazione. Di seguito è riportato un esempio.

  • username "Autorizzazione" (a scopo illustrativo)
  • password J9adfdsafc3RfMjpVU1yif5XMw” (a scopo illustrativo)

Casella personale SFTP per Push

Percorso Dropbox: partnerupload.google.com:19321

AVVISO: i file caricati in questa casella di posta SFTP vengono eliminati automaticamente dopo 24 ore.

Autenticazione endpoint

  • Coppia di chiavi pubblica/privata (consigliato)

    • Segui questo tutorial per generare le coppie di chiavi.
    • Invia a LSA la chiave pubblica e conserva la chiave privata per l'autenticazione
    • LSA utilizzerà la chiave pubblica per generare un nome utente e inviarlo all'aggregatore

  • Autenticazione con password

    • LSA genererà il nome utente e la password e li invierà di nuovo all'aggregatore.

Riferimento rapido ai comandi SFTP

  1. Accedi. Utilizza questo comando per accedere. Ometti -i se non utilizzi una chiave privata.

    sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.com

  2. Copia il file. Copia il file nel sistema remoto. Puoi utilizzare lls/lcd per ls/cd nel tuo sistema locale per trovare il file. Quindi copia il file tramite:

    put <path_to_local_file>

  3. Verifica. Utilizza ls per visualizzare un elenco di cartelle e file nella directory SFTP e verificare che il file sia stato copiato nel sistema remoto.

Categorie del feed

Come indicato in precedenza, ogni feed è analogo a un file ed è costituito da diversi elementi del feed. Ogni elemento del feed contiene dati relativi a un particolare fornitore (ID attività univoco). Ogni feed ha anche un timestamp che indica la data di aggiornamento del feed. Categoria feed specifica il modo in cui gli annunci di Servizi locali interpretano un determinato feed. Esistono due categorie di feed, come descritto di seguito.

Il feed snapshot contiene un elenco completo di fornitori (in un aggregatore) in un determinato timestamp. Dopo l'elaborazione di questo feed di snapshot, si applicano le seguenti semantiche:

  • Per qualsiasi fornitore presente nel feed, il sistema aggiornerà i dati di questo fornitore nel database LSA (ad es. creerà un nuovo fornitore se viene rilevato per la prima volta o aggiornerà i dati del fornitore se è stato elaborato in un feed precedente).

  • Per qualsiasi fornitore nell'aggregatore attualmente presente nel database LSA, ma mancante nel feed, il fornitore verrà eliminato.

Il feed di aggiornamento (o incrementale) contiene un elenco parziale di fornitori (in un aggregatore) in un determinato timestamp. Dopo l'elaborazione di un feed incrementale, verranno applicate le seguenti semantiche:

  • Per qualsiasi fornitore presente nel feed, il sistema aggiornerà i dati per questo fornitore nel database LSA se il fornitore è stato creato in un feed snapshot precedente. Ad esempio, se un fornitore viene rilevato per la prima volta, non verrà eseguita alcuna operazione.

  • Per qualsiasi fornitore attualmente presente nel database LSA, ma mancante nel feed, questa operazione non ha effetto (ovvero, non verrà apportata alcuna modifica a questo fornitore).

La semantica per il feed dei profili e delle recensioni è leggermente diversa. Consulta la semantica dei singoli feed per i dettagli di elaborazione.

Feed dei profili: * Feed snapshot basati su pull * Feed snapshot basati su push * Feed di aggiornamento basati su push Feed delle recensioni: * Feed snapshot basati su pull * Feed snapshot basati su push

Sono necessari feed di profili separati per:

  1. Fornitori ritenuti idonei al badge Protezione Google o Verificato da Google.

  2. Fornitori non idonei al badge.

Esempi

Feed degli snapshot

Ricorda che un feed snapshot è costituito da un elenco completo di fornitori. Ad esempio, se un aggregatore vuole che vengano inseriti 100 fornitori in LSA, il feed snapshot deve contenere lo stato più recente di tutti i 100 fornitori.

Come funziona

Di seguito è riportato un semplice esempio che mostra come funziona la categoria snapshot dei feed dei profili.

  • Snapshot 1 ha Pro 1, Pro 2
  • Snapshot 2 ha Pro 1, Pro 3

Dopo l'elaborazione dello snapshot 1, il database LSA conterrà Pro 1 e Pro 2. Durante l'elaborazione dello Snapshot 2, LSA aggiornerà Pro 1, creerà Pro 3 ed eliminerà Pro 2. ovvero, dopo l'elaborazione dello snapshot 2, il database LSA conterrà Pro 1 e Pro 3.

Aggiornare i feed (incrementali)

Ricorda che un feed di aggiornamento contiene un elenco parziale di fornitori in un aggregatore. Ad esempio, se un aggregatore vuole aggiornare solo 5 dei 100 fornitori forniti in precedenza, il feed di aggiornamento deve contenere solo lo stato più recente di questi 5 fornitori.

Come funziona

Di seguito è riportato un semplice esempio che mostra come funziona la categoria di aggiornamento "feed dei profili".

  • Aggiornamento 1: Pro 1, Pro 2
  • Aggiornamento 2: Pro 1, Pro 3

Dopo l'elaborazione dell'aggiornamento 1, il database LSA conterrà Pro 1 e Pro 2. Durante l'elaborazione dell'aggiornamento 2, LSA aggiornerà Pro 1 e creerà Pro 3. Tieni presente che Pro 2 non viene modificato. ovvero, dopo l'elaborazione dell'aggiornamento 2, il database LSA conterrà Pro1, Pro2 e Pro 3.

Implicazioni di Snapshot e Pull

Il meccanismo snapshot feeds + pull implica le seguenti limitazioni:

  • Potrebbe verificarsi un ritardo di alcune ore prima che i partner possano aggiungere o eliminare fornitori, aggiornare le informazioni del profilo, mettere in pausa gli annunci o modificare i budget. Il ritardo è direttamente correlato alla frequenza delle richieste pull.
  • Per gli aggiornamenti urgenti dei dati, potremmo dover supportare manualmente un pull una tantum/ad hoc.

Implicazioni del supporto incrementale e push

L'apertura del meccanismo Aggiorna feed + push comporta i seguenti miglioramenti:

  • I partner possono fornire il feed degli snapshot in modalità push o pull. I partner che preferiscono non gestire l'endpoint (per il pull) possono utilizzare il push per ridurre il costo di manutenzione dell'endpoint. I partner che già supportano i feed di snapshot in pull possono continuare a fornire snapshot in pull.
  • I partner possono utilizzare gli incrementali per aggiornare solo un sottoinsieme di fornitori con modifiche al profilo. Ciò migliora l'aggiornamento dei dati del profilo.
  • Per quanto riguarda la scelta tra snapshot e incrementali, push e pull, consulta questa sezione per l'approccio di integrazione consigliato.

I partner sono tenuti a disporre di feed di snapshot periodici, tramite push o pull. Ciò consente a LSA di gestire emergenze come rollback e ripristino del sistema in caso di aggiornamenti mancati.

  • Con il meccanismo push, i partner devono eseguire il push dei feed dei profili snapshot ogni 2 ore e rivedere i feed ogni 6 ore per garantire l'aggiornamento dei dati di base.
  • Con il meccanismo pull, gli annunci di Servizi locali recuperano i feed dei profili snapshot ogni 2 ore e i feed delle recensioni ogni 6 ore per garantire l'aggiornamento dei dati di base.
  • I partner hanno bisogno di uno solo dei meccanismi (push o pull), ma non entrambi, per fornire i feed degli snapshot.

Se vuoi migliorare l'aggiornamento dei dati, puoi inviare feed di aggiornamento tramite push. Gli annunci di Servizi locali non estraranno i feed di aggiornamento.

  • I feed di aggiornamento vengono utilizzati per propagare gli elementi modificati dall'ultimo snapshot senza attendere lo snapshot successivo.
  • LSA consiglia ai fornitori di avere un intervallo superiore a 5 minuti tra due push.
  • Ti consigliamo di raggruppare in modo ragionevole gli elementi del feed in un feed di aggiornamento. Per aggiornare 5 fornitori, LSA preferisce che i fornitori inviino un feed di aggiornamento con 5 elementi del feed anziché 5 feed di aggiornamento con 1 elemento del feed ciascuno.
  • Gli annunci di Servizi locali supportano i feed incrementali solo per i feed dei profili, non per i feed delle recensioni.

Gli annunci di Servizi locali rispetteranno il campo feedTimestampMicros nei metadati per garantire la coerenza dei dati. Un elemento del feed con un timestamp precedente verrà ignorato per evitare di introdurre dati obsoleti se è stato inserito un elemento più recente che aggiorna lo stesso professionista. È responsabilità del partner riflettere correttamente l'aggiornamento dei dati utilizzando feedTimestampMicros sia nei feed snapshot che in quelli di aggiornamento.

I partner devono utilizzare l'API Reporting per ottenere informazioni sui lead e sugli addebiti per fornitore.