Überblick über die Integration

Mit Google Lokale Dienstleistungen können Aggregatoren ihre Einträge (oder Anbieter) auf Google.com präsentieren. In diesem Leitfaden wird beschrieben, wie Aggregatoren strukturierte Daten zu ihren Anbietern für Google Lokale Dienstleistungen bereitstellen können. Wir dokumentieren insbesondere die API-Endpunkte, die Aggregatoren für die Integration in LSA implementieren müssen.

Glossar

Aggregator (oder Partner): Das sind Partner, die Anbieter aggregieren, denen sie Dienste zur Verfügung stellen und deren Daten an LSA weitergegeben werden können.

Drittanbieter (oder Eintrag): Das sind die einzelnen kleinen Unternehmen (z.B. Joe’s Plumbing) haben möglicherweise eine Geschäftsbeziehung mit Aggregatoren. Aggregatoren stellen Google Lokale Dienstleistungen Informationen zu diesen Unternehmen zur Verfügung.

Übersicht

Aggregatoren stellen Local Services über Feeds Daten zu ihren Anbietern (Unternehmen) zur Verfügung. Jeder Feed enthält Daten zu mehreren Anbietern. In einem Feed werden Daten zu einem einzelnen Anbieter in einem Feedeintrag zusammengefasst. Jeder Feed enthält auch einen Zeitstempel, der angibt, wie aktuell der Feed ist. In jedem Feed wird auch ein Feedtyp angegeben. Das können Daten zum Anbieterprofil oder zu Anbieterrezensionen sein, wie unten beschrieben.

Feedtypen

Für die erste Integration kann jeder Feed einer der folgenden Feedtypen sein:

• Profil-Feeds: Dieser Feed enthält Informationen zu Anbieterprofilen. Jedes Feed-Element enthält Profilinformationen zu einem bestimmten Anbieter. Dazu gehören eine eindeutige Unternehmens-ID, der Name des Unternehmens, die Standorte, an denen das Unternehmen tätig ist, die angebotenen Dienstleistungen und die Öffnungszeiten. Das Feed-Element enthält auch Serving-Metadaten für dieses Unternehmen, z.B. das monatliche Budget und den Anzeigenstatus.

• Rezensionsfeeds: Dieser Feed enthält Informationen zu Rezensionen von Anbietern. Jedes Feedelement enthält eine Liste mit detaillierten Nutzerrezensionen für einen bestimmten Anbieter. Jede Kundenrezension besteht aus dem Namen des Kunden, der Bewertung (1 bis 5), dem Rezensionstext, dem Zeitstempel der Rezension usw.

Weitere Informationen zu den einzelnen Feldern und ihrer Semantik finden Sie unter Profilfeed und Rezensionsfeed.

Feedaufnahme

Feeddaten werden als JSON serialisiert. Für das Einreichen von Daten wird in LSA nur ein Pull-Mechanismus unterstützt. Es ist geplant, in Zukunft einen Push-Mechanismus zu unterstützen.

Pull-Mechanismus

Beim Pull-Mechanismus unterstützen Aggregatoren eine Reihe vordefinierter REST-Endpunkte (URLs), über die JSON-Objekte gesendet und empfangen werden. Das ist vergleichbar mit dem Hosten einer oder mehrerer Dateien auf einem Webserver. LSA sendet regelmäßig HTTP-GET-Anfragen an diese URLs, um Daten abzurufen. Details zu den vordefinierten URLs finden Sie im nächsten Abschnitt zu API-Endpunkten.

Push-Mechanismus

Beim Push-Mechanismus stellt LSA einen Endpunkt bereit, den Aggregatoren aufrufen und Daten bereitstellen können. Semantisch entspricht dies einem Pull, bietet aber Flexibilität in Fällen, in denen Aggregatoren bestimmte Daten an Local Services senden möchten. Alle im Protokoll beschriebenen Semantiken, Regeln oder Einschränkungen gelten gleichermaßen für Push und Pull.

API-Endpunkte

Die folgenden Endpunkte sollten von Dienstleistern für Rezensionen unterstützt werden: einer für den Profilfeed und einer für den Rezensionsfeed.

Empfohlener Endpunktpfad

Wir empfehlen, dass die Endpunkte Versionsinformationen wie unten enthalten. Wir beginnen mit v1.

Endpunkt	Pfad
Profilfeed	/feeds/{version}/profile
Rezensionsfeed	/feeds/{version}/review

Endpunktparameter

Parameter	Beschreibung
maxresults	Dies ist das Limit für die Anzahl der Feedelemente, die auf einer Seite angefordert werden können.
nextpagetoken	Paginierungstoken zum Abrufen der nächsten Ergebnisseite

Endpunkt-Authentifizierung

Für die Authentifizierung wird die HTTP-Basisauthentifizierung verwendet: base64-codierter Nutzername und base64-codiertes Passwort für die Authentifizierung. Ein Beispiel dafür sehen Sie unten.

• username „Autorisierung“ (zur Veranschaulichung)
• password J9adfdsafc3RfMjpVU1yif5XMw“ (zur Veranschaulichung)

SFTP-Dropbox für Push

Dropbox-Pfad: partnerupload.google.com:19321

ACHTUNG: Dateien, die in diese SFTP-Ablage hochgeladen werden, werden nach 24 Stunden automatisch gelöscht.

Endpunkt-Authentifizierung

• Schlüsselpaar mit öffentlichem/privatem Schlüssel (empfohlen)

  • Hier finden Sie eine Anleitung zum Generieren von Schlüsselpaaren.
  • Senden Sie den öffentlichen Schlüssel an LSA und behalten Sie den privaten Schlüssel für die Authentifizierung.
  • LSA verwendet den öffentlichen Schlüssel, um einen Nutzernamen zu generieren und an den Aggregator zurückzusenden.

• Passwortauthentifizierung

  • LSA generiert den Nutzernamen und das Passwort und sendet sie an den Aggregator zurück.

SFTP-Befehlsreferenz

1. Anmelden Verwenden Sie diesen Befehl, um sich anzumelden. Lassen Sie „-i“ weg, wenn Sie keinen privaten Schlüssel verwenden.

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

2. Datei kopieren: Kopieren Sie die Datei in das Remotesystem. Sie können lls/lcd verwenden, um ls/cd in Ihr lokales System zu wechseln und die Datei zu suchen. Kopieren Sie die Datei dann über:

   put <path_to_local_file>

3. Bestätigen Mit ls können Sie eine Liste der Ordner und Dateien im SFTP-Verzeichnis aufrufen und prüfen, ob Ihre Datei auf das Remotesystem kopiert wurde.

Feedkategorien

Wie bereits erwähnt, entspricht jeder Feed einer Datei und besteht aus mehreren Feedeinträgen. Jedes Feedelement enthält Daten zu einem bestimmten Anbieter (eindeutige Unternehmens-ID). Jeder Feed hat auch einen Zeitstempel, der angibt, wie aktuell der Feed ist. Mit Feedkategorie wird festgelegt, wie LSA einen bestimmten Feed interpretiert. Es gibt zwei Kategorien von Feeds, wie unten beschrieben.

Der Snapshot-Feed enthält eine vollständige Liste der Anbieter (unter einem Aggregator) zu einem bestimmten Zeitstempel. Nach der Verarbeitung dieses Snapshot-Feeds gelten die folgenden Semantiken:

• Für jeden im Feed enthaltenen Anbieter werden die Daten für diesen Anbieter in der Datenbank für lokale Dienstleistungen aktualisiert. Das System erstellt beispielsweise einen neuen Anbieter, wenn dieser zum ersten Mal gefunden wird, oder aktualisiert die Anbieterdaten, wenn der Anbieter in einem früheren Feed verarbeitet wurde.

• Alle Anbieter unter dem Aggregator, die derzeit in der LSA-Datenbank vorhanden sind, aber im Feed fehlen, werden gelöscht.

Der Aktualisierungs- oder inkrementelle Feed enthält eine Teilliste von Anbietern (unter einem Aggregator) zu einem bestimmten Zeitstempel. Nach der Verarbeitung eines inkrementellen Feeds gelten die folgenden Regeln:

• Für jeden im Feed enthaltenen Anbieter werden die Daten für diesen Anbieter in der Datenbank für lokale Dienstleistungen aktualisiert, sofern der Anbieter in einem früheren Snapshot-Feed erstellt wurde. (z.B. wenn ein Anbieter zum ersten Mal gefunden wird, wird nichts unternommen)

• Für Anbieter, die derzeit in der Datenbank für lokale Dienstleistungen vorhanden sind, aber im Feed fehlen, passiert nichts (d.h., es gibt keine Änderung an diesem Anbieter).

Die Semantik für Profil- und Rezensionsfeeds ist etwas unterschiedlich. Weitere Informationen zur Verarbeitung finden Sie in der Semantik der einzelnen Feeds.

Profilfeeds: * Pull-basierte Snapshot-Feeds * Push-basierte Snapshot-Feeds * Push-basierte Update-Feeds Rezensionsfeeds: * Pull-basierte Snapshot-Feeds * Push-basierte Snapshot-Feeds

Separate Profil-Feeds sind für Folgendes erforderlich:

1. Anbieter, die für das Google Käuferschutz-Logo oder das Google Screened-Symbol infrage kommen.

2. Anbieter, die nicht für das Gütesiegel infrage kommen.

Beispiele

Snapshot-Feeds

Ein Snapshot-Feed enthält eine vollständige Liste der Anbieter. Wenn ein Aggregator beispielsweise 100 Anbieter in lokale Dienstleistungen aufnehmen möchte, sollte der Snapshot-Feed den aktuellen Status aller 100 Anbieter enthalten.

Funktionsweise

Unten sehen Sie ein einfaches Beispiel für die Funktionsweise der Snapshot-Kategorie von Profil-Feeds.

• Snapshot 1 enthält Pro 1 und Pro 2.
• Snapshot 2 hat Pro 1, Pro 3

Nach der Verarbeitung von Snapshot 1 enthält die Datenbank für lokale Dienstleistungen „Pro 1“ und „Pro 2“. Während der Verarbeitung von Snapshot 2 aktualisiert LSA Profil 1, erstellt Profil 3 und löscht Profil 2. Nach der Verarbeitung von Snapshot 2 enthält die LSA-Datenbank also Pro 1 und Pro 3.

Feeds aktualisieren (inkrementell)

Ein Update-Feed enthält eine Teilliste von Anbietern unter einem Aggregator. Wenn ein Aggregator beispielsweise nur 5 der zuvor bereitgestellten 100 Anbieter aktualisieren möchte, muss der Update-Feed nur den aktuellen Status für diese 5 Anbieter enthalten.

Funktionsweise

Unten sehen Sie ein einfaches Beispiel für die Funktionsweise der Updatekategorie „Profil-Feeds“.

• Update 1: Pro 1, Pro 2
• Update 2: Pro 1, Pro 3

Nach der Verarbeitung von Update 1 enthält die LSA-Datenbank Pro 1 und Pro 2. Während der Verarbeitung von Update 2 aktualisiert LSA Pro 1 und erstellt Pro 3. Die Pro 2 bleibt unverändert. Nach der Verarbeitung von Update 2 enthält die LSA-Datenbank also Pro1, Pro2 und Pro3.

Auswirkungen von Snapshot und Pull

Der Mechanismus Snapshot-Feeds + Pull hat die folgenden Einschränkungen zur Folge:

• Es kann einige Stunden dauern, bis Partner Anbieter hinzufügen oder löschen, Profilinformationen aktualisieren, Anzeigen pausieren oder Budgets ändern können. Die Verzögerung hängt direkt von der Häufigkeit der Pull-Anfragen ab.
• Bei dringenden Datenaktualisierungen müssen wir möglicherweise einen einmaligen/Ad-hoc-Pull manuell unterstützen.

Auswirkungen von inkrementellem und Push-Support

Die Öffnung des Mechanismus Feeds aktualisieren + Push bringt folgende Verbesserungen mit sich:

• Partner können den Snapshot-Feed entweder per Push oder Pull bereitstellen. Partner, die den Endpunkt (für Pull) nicht verwalten möchten, können stattdessen Push verwenden, um die Kosten für die Endpunktwartung zu senken. Partner, die bereits Snapshot-Feeds im Pull-Verfahren unterstützen, können weiterhin Snapshots im Pull-Verfahren bereitstellen.
• Partner können mit Inkrementen nur eine Teilmenge von Anbietern mit Profiländerungen aktualisieren. Dadurch wird die Aktualität der Profildaten verbessert.
• Informationen zur Auswahl von Snapshots im Vergleich zu inkrementellen Daten sowie von Push- im Vergleich zu Pull-Vorgängen finden Sie in diesem Abschnitt unter „Empfohlener Integrationsansatz“.

Empfohlene Integrationsmethode

Partner müssen regelmäßig Snapshot-Feeds bereitstellen, entweder per Push oder Pull. So kann LSA Notfälle wie Rollbacks und Systemwiederherstellung im Falle verpasster Updates bewältigen.

• Mit dem Push-Mechanismus sollten Partner alle zwei Stunden Snapshot-Profil-Feeds und alle sechs Stunden Review-Feeds senden, um die Aktualität der Basisdaten zu gewährleisten.
• Mit dem Pull-Mechanismus werden alle zwei Stunden Snapshot-Profil-Feeds und alle sechs Stunden Review-Feeds abgerufen, um die Aktualität der Baseline-Daten zu gewährleisten.
• Partner benötigen nur einen der Mechanismen (entweder Push oder Pull), aber nicht beide, um Snapshot-Feeds bereitzustellen.

Partner, die die Datenaktualität verbessern möchten, können optional Updatefeeds per Push senden. LSA ruft keine Update-Feeds ab.

• Mit Update-Feeds werden geänderte Artikel seit dem letzten Snapshot weitergegeben, ohne dass auf den nächsten Snapshot gewartet werden muss.
• Bei LSA wird empfohlen, dass zwischen zwei Push-Benachrichtigungen ein Intervall von mehr als 5 Minuten liegt.
• Wir empfehlen, Feedelemente in einem Update-Feed sinnvoll zu bündeln. Wenn Sie fünf Anbieter aktualisieren möchten, sollten Sie einen Update-Feed mit fünf Feed-Elementen senden, anstatt fünf Update-Feeds mit jeweils einem Feed-Element.
• Für lokale Dienstleistungsanzeigen werden inkrementelle Feeds nur für Profilfeeds, nicht für Rezensionsfeeds unterstützt.

Bei lokalen Serviceanzeigen wird das Feld feedTimestampMicros in den Metadaten berücksichtigt, um die Datenkonsistenz zu gewährleisten. Ein Feedelement mit einem älteren Zeitstempel wird übersprungen, um zu vermeiden, dass veraltete Informationen eingeführt werden, wenn ein neueres Element, das dieselbe Fachkraft aktualisiert, aufgenommen wurde. Der Partner ist dafür verantwortlich, die Aktualität der Daten mithilfe von feedTimestampMicros in Snapshot- und Update-Feeds korrekt anzugeben.

Partner sollten die Reporting API verwenden, um Informationen zu Leads und Gebühren pro Anbieter zu erhalten.