Reklamy usług lokalnych (LSA) umożliwiają partnerom współpracę z agregatorami w celu wyświetlania ich informacji (lub dostawców) w Google.com. W tym przewodniku opisujemy, jak agregatorzy mogą przekazywać do LSA dane strukturalne o swoich dostawcach. W szczególności dokumentujemy zestaw punktów końcowych interfejsu API, które agregatory muszą wdrożyć, aby zintegrować się z LSA.
Słowniczek
Agregator (lub partner): są to partnerzy, którzy agregują dostawców, którym świadczą usługi, a ich dane mogą być przekazywane do LSA.
Dostawca zewnętrzny (lub wizytówka): są to małe firmy (np. Joe’s plumbing), które mogą współpracować z agregatorami. Agregatory przekazują do Usług Lokalnych informacje o tych firmach.
Przegląd
Agregatorzy będą przesyłać do Usług lokalnych dane o swoich dostawcach (firmach) za pomocą plików danych. Każdy plik danych zawiera informacje o wielu dostawcach. W pliku danych informacje o jednym dostawcy są zawarte w elemencie pliku danych. Każdy plik danych zawiera też sygnaturę czasową, która określa jego aktualność. Każdy plik danych określa też typ pliku danych: może to być opis profilu dostawcy lub opinie o dostawcy, jak opisano poniżej.
Typy plików danych
Na potrzeby wstępnej integracji każdy plik danych może być jednym z tych typów:
Pliki danych profilu: ten plik danych zawiera informacje o profilach dostawców. Każdy element pliku danych zawiera informacje o profilu konkretnego dostawcy. Obejmuje to niepowtarzalny identyfikator firmy, nazwę firmy, lokalizacje, w których świadczy ona usługi, oferowane usługi, godziny pracy itp. Element pliku danych zawiera też metadane wyświetlania tej firmy (np.wysokość miesięcznego budżetu, stan reklamy itp.).
Pliki danych z opiniami: ten plik danych zawiera informacje o opiniach o dostawcach. Każdy element pliku danych zawiera listę szczegółowych opinii konsumentów o konkretnym dostawcy. Każda opinia konsumencka zawiera imię i nazwisko konsumenta, ocenę (1–5), tekst opinii, sygnaturę czasową opinii itp.
Więcej informacji o poszczególnych polach i ich semantyce znajdziesz w sekcjach Plik danych o profilu i Plik danych z opiniami.
Przetwarzanie pliku danych
Dane pliku danych są serializowane jako JSON. Aby przesyłać dane, LSA będzie obsługiwać tylko mechanizm pobierania. W przyszłości planujemy wprowadzić obsługę mechanizmu push.
Mechanizm pobierania
W mechanizmie pobierania agregatory obsługują zestaw predefiniowanych punktów końcowych REST (adresów URL), które wysyłają i odbierają obiekty JSON. Jest to analogiczne do hostowania co najmniej 1 pliku na serwerze WWW. LSA będzie okresowo wysyłać żądania HTTP GET do tych adresów URL, aby pobierać dane. Szczegółowe informacje o wstępnie zdefiniowanych adresach URL znajdziesz w następnej sekcji dotyczącej punktów końcowych interfejsu API.
Mechanizm push
W mechanizmie push lokalne usługi reklamowe udostępniają punkt końcowy, do którego agregatory mogą dzwonić i przekazywać dane. Semantycznie jest to to samo co pobieranie, ale zapewnia elastyczność w przypadkach, gdy agregatorzy chcą przesyłać określone dane do Reklam Usług Lokalnych. Wszystkie semantyki, reguły i ograniczenia opisane w protokole mają zastosowanie zarówno do wysyłania, jak i pobierania w ten sam sposób.
Punkty końcowe interfejsu API
Pośrednicy powinni obsługiwać te punkty końcowe: jeden dla pliku danych o profilu i jeden dla pliku danych z opiniami.
Ścieżka zalecanych punktów końcowych
Zalecamy, aby punkty końcowe zawierały informacje o wersji, takie jak poniżej. Zaczynamy od v1.
| Punkt końcowy | Ścieżka |
|---|---|
| Plik danych profilu | /feeds/{version}/profile |
| Sprawdź plik danych | /feeds/{version}/review |
Parametr punktu końcowego
| Parametry | Opis |
|---|---|
maxresults |
Jest to limit liczby pozycji w pliku danych, o które można poprosić na stronie. |
nextpagetoken |
Token stronicowania umożliwiający pobranie następnej strony wyników. |
Uwierzytelnianie punktów końcowych
Uwierzytelnianie odbywa się za pomocą podstawowego uwierzytelniania dostępu HTTP: nazwa użytkownika i hasło zakodowane w formacie base64. Poniżej prezentujemy przykład.
username„Authorization” (do celów ilustracyjnych)passwordJ9adfdsafc3RfMjpVU1yif5XMw” (do celów ilustracyjnych)
Skrzynka referencyjna SFTP dla Push
Ścieżka w Dropbox: partnerupload.google.com:19321
OSTRZEŻENIE: pliki przesłane do tego folderu SFTP są automatycznie usuwane po 24 godzinach.
Uwierzytelnianie punktów końcowych
Para klucz publiczny/klucz prywatny (zalecana)
- Aby wygenerować pary kluczy, skorzystaj z tego samouczka.
- Prześlij klucz publiczny do LSA i zachowaj klucz prywatny na potrzeby uwierzytelniania.
- LSA użyje klucza publicznego do wygenerowania nazwy użytkownika i przesłania jej z powrotem do agregatora.
Uwierzytelnianie za pomocą hasła
- LSA wygeneruje nazwę użytkownika i hasło i prześle je do agregatora.
Szybki przewodnik po poleceniach SFTP
Zaloguj się. Aby się zalogować, użyj tego polecenia. (Pomiń -i
jeśli nie używasz klucza prywatnego). sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.comSkopiuj plik. Skopiuj plik do systemu zdalnego. Możesz użyć
lls/lcdtols/cdw systemie lokalnym, aby znaleźć plik. Następnie skopiuj plik, korzystając z jednej z tych metod:put <path_to_local_file>Zweryfikuj Użyj polecenia
ls, aby wyświetlić listę folderów i plików w katalogu SFTP i sprawdzić, czy plik został skopiowany do systemu zdalnego.
Kategorie plików danych
Jak wspomnieliśmy wcześniej, każdy plik danych jest analogiczny do pliku i składa się z kilku elementów pliku danych. Każdy element pliku danych zawiera informacje o konkretnym dostawcy (unikalny identyfikator firmy). Każdy plik danych ma też sygnaturę czasową, która określa jego aktualność. Kategoria pliku danych określa, jak LSA interpretuje dany plik danych. Istnieją 2 kategorie plików danych, które opisaliśmy poniżej.
Plik danych z migawką zawiera pełną listę dostawców (w ramach agregatora) w określonym momencie. Po przetworzeniu tego pliku danych z migawką obowiązują te zasady semantyczne:
W przypadku każdego dostawcy obecnego w pliku danych system zaktualizuje dane tego dostawcy w bazie danych reklam lokalnych (np. utworzy nowego dostawcę, jeśli pojawi się on po raz pierwszy, lub zaktualizuje dane dostawcy, jeśli został on przetworzony w poprzednim pliku danych).
W przypadku każdego dostawcy w ramach agregatora, który jest obecnie w bazie danych LSA, ale nie ma go w pliku danych, dostawca zostanie usunięty.
Plik danych z aktualizacją (lub przyrostowy) zawiera częściową listę dostawców (w ramach agregatora) z określoną sygnaturą czasową. Po przetworzeniu pliku danych przyrostowych obowiązują te zasady:
W przypadku każdego dostawcy obecnego w pliku system zaktualizuje dane tego dostawcy w bazie danych reklam lokalnych usług, jeśli dostawca został utworzony we wcześniejszym pliku migawki. (np. jeśli dostawca jest napotkany po raz pierwszy, nie będzie to miało żadnego wpływu);
W przypadku każdego dostawcy, który jest obecnie w bazie danych LSA, ale nie ma go w pliku danych, ta operacja nie będzie miała żadnego efektu (tzn. nie nastąpi żadna zmiana w przypadku tego dostawcy).
Semantyka profilu i pliku danych z opiniami jest nieco zróżnicowana. Szczegółowe informacje o przetwarzaniu znajdziesz w sekcji dotyczącej semantyki poszczególnych plików danych.
Pliki danych profilu: * Pliki danych typu Snapshot oparte na pobieraniu * Pliki danych typu Snapshot oparte na wysyłaniu * Pliki danych typu Update oparte na wysyłaniu Pliki danych z opiniami: * Pliki danych typu Snapshot oparte na pobieraniu * Pliki danych typu Snapshot oparte na wysyłaniu
Wymagane są osobne pliki danych profilu w przypadku:
Usługodawcy, którzy kwalifikują się do uzyskania odznaki Ochrona Google lub Sprawdzone przez Google.
Dostawcy, którzy nie kwalifikują się do otrzymania plakietki.
Przykłady
Karty zrzutów
Pamiętaj, że plik danych z migawką zawiera pełną listę dostawców. Jeśli na przykład agregator chce, aby do Reklam Usług Lokalnych zostało zaimportowanych 100 usługodawców, plik danych migawki powinien zawierać najnowsze informacje o wszystkich 100 usługodawcach.
Jak to działa
Poniżej znajdziesz prosty przykład pokazujący, jak działa kategoria migawek w profilu.
- Snapshot 1 ma Pro 1, Pro 2
- Zrzut 2 zawiera Pro 1 i Pro 3
Po przetworzeniu migawki 1 w bazie danych Reklam Usług Lokalnych będą dostępne profile Pro 1 i Pro 2. Podczas przetwarzania zrzutu 2 usługa LSA zaktualizuje profil 1, utworzy profil 3 i usunie profil 2. Oznacza to, że po przetworzeniu zrzutu 2 w bazie danych LSA będą znajdować się usługi Pro 1 i Pro 3.
Aktualizowanie plików danych (przyrostowo)
Pamiętaj, że kanał aktualizacji zawiera częściową listę dostawców w ramach agregatora. Jeśli na przykład agregator chce zaktualizować tylko 5 ze 100 wcześniej podanych dostawców, plik danych aktualizacji musi zawierać tylko najnowsze informacje o tych 5 dostawcach.
Jak to działa
Poniżej znajdziesz prosty przykład pokazujący, jak działa kategoria aktualizacji „pliki danych o profilach”.
- Aktualizacja 1: Pro 1, Pro 2
- Aktualizacja 2: Pro 1, Pro 3
Po przetworzeniu aktualizacji 1 w bazie danych Reklam Usług Lokalnych będą dostępne profile Pro 1 i Pro 2. Podczas przetwarzania aktualizacji 2 usługa LSA zaktualizuje profil Pro 1 i utworzy profil Pro 3. Pamiętaj, że Pro 2 pozostaje bez zmian. Oznacza to, że po przetworzeniu aktualizacji 2 baza danych LSA będzie zawierać Pro1, Pro2 i Pro3.
Konsekwencje zrzutu i pobierania
Mechanizm kanałów z migawkami + pobieranie wiąże się z tymi ograniczeniami:
- Dodawanie i usuwanie dostawców, aktualizowanie informacji o profilu, wstrzymywanie reklam i zmiana budżetów może potrwać kilka godzin. Opóźnienie jest bezpośrednio związane z częstotliwością żądań pobierania.
- W przypadku pilnych aktualizacji danych możemy ręcznie obsługiwać jednorazowe/ad hoc pobieranie.
Konsekwencje obsługi przyrostowej i push
Otwarcie mechanizmu aktualizacji plików danych i wypychania oznacza wprowadzenie tych ulepszeń:
- Partnerzy mogą dostarczać plik danych w formie push lub pull. Partnerzy, którzy nie chcą utrzymywać punktu końcowego (w przypadku pobierania), mogą zamiast tego używać wysyłania, aby obniżyć koszt utrzymania punktu końcowego. Partner, który obsługuje już zrzuty w przypadku pobierania, może nadal dostarczać zrzuty w ten sposób.
- Partnerzy mogą używać przyrostowych aktualizacji, aby zmieniać tylko podzbiór dostawców. Zwiększa to częstotliwość aktualizacji danych profilu.
- W sekcji dotyczącej zalecanego podejścia do integracji znajdziesz informacje o tym, jak wybrać migawkę lub przyrostowe dane, a także metodę push lub pull.
Zalecane podejście do integracji
Partnerzy muszą mieć okresowe pliki danych zrzutów, niezależnie od tego, czy są one przesyłane, czy pobierane. Dzięki temu LSA może obsługiwać sytuacje awaryjne, takie jak wycofywanie zmian i przywracanie systemu w przypadku pominięcia aktualizacji.
- W przypadku mechanizmu push partnerzy powinni przesyłać pliki danych profilu co 2 godziny, a pliki danych opinii co 6 godzin, aby zagwarantować podstawową aktualność danych.
- W przypadku mechanizmu pobierania LSA będzie pobierać pliki danych profilu co 2 godziny, a pliki danych z opiniami co 6 godzin, aby zagwarantować podstawową aktualność danych.
- Partnerzy potrzebują tylko jednego mechanizmu (push lub pull), ale nie obu, do dostarczania plików danych stanu.
Opcjonalnie partnerzy, którzy chcą zwiększyć częstotliwość aktualizacji danych, mogą przesyłać pliki danych aktualizacji za pomocą pusha. LSA nie będzie pobierać plików danych z aktualizacjami.
- Pliki danych aktualizacji służą do propagowania zmienionych elementów od czasu ostatniego zrzutu bez czekania na kolejny zrzut.
- LSA zaleca, aby odstęp między dwoma powiadomieniami wynosił ponad 5 minut.
- Zalecamy rozsądne grupowanie elementów pliku danych w pliku danych aktualizacji. Aby zaktualizować 5 dostawców, LSA woli, aby dostawcy przesyłali 1 plik danych z aktualizacjami zawierający 5 elementów pliku danych, zamiast przesyłać 5 plików danych z aktualizacjami, z których każdy zawiera 1 element pliku danych.
- LSA obsługuje dodatkowe pliki danych tylko w przypadku plików danych o profilu, a nie plików danych z opiniami.
LSA będzie uwzględniać pole feedTimestampMicros w metadanych, aby zagwarantować spójność danych. Pozycja w pliku danych ze starszą sygnaturą czasową zostanie pominięta, aby uniknąć wprowadzenia nieaktualnych informacji, jeśli została już przetworzona nowsza pozycja, która aktualizuje ten sam produkt. Za prawidłowe odzwierciedlenie aktualności danych za pomocą elementu feedTimestampMicros w pliku danych z rzutem i pliku danych z aktualizacją odpowiada partner.
Partnerzy powinni korzystać z interfejsu Reporting API, aby uzyskiwać informacje o potencjalnych klientach i opłatach za każdego dostawcę.