RTU są przeznaczone głównie do aktualizacji, których nie można przewidzieć, np. w przypadku nagłego zamknięcia lub metadanych, które okresowo się zmieniają (np. szacowanego czasu dojazdu). Jeśli zmiana nie musi być odzwierciedlona natychmiast, możesz zamiast tego użyć zbiorczego przesyłania plików danych. Aktualizacje w czasie rzeczywistym są przetwarzane w ciągu maksymalnie 5 minut.
Konfiguracja Google Cloud Platform
- Skonfiguruj projekt GCP. Aby uzyskać dostęp do interfejsu RTU API, musisz mieć projekt GCP.
- Przyznaj dostęp do edycji food-support@google.com
- Poinformuj osobę kontaktową w Google o numerze projektu GCP.Aby aktualizacje w czasie rzeczywistym działały, projekt GCP musi być powiązany z Twoim kontem w Centrum działań.
- Włącz interfejs Maps Booking API:
- W GCP otwórz Interfejsy API i usługi > Biblioteka.
- Wyszukaj „Google Maps Booking API”.
- Znajdź instancję piaskownicy („Google Maps Booking API (Dev)”) i kliknij Włącz.
- Znajdź instancję produkcyjną („Google Maps Booking API”) i kliknij Włącz.
- Utwórz w projekcie GCP konto usługi z rolą edytującego. Więcej informacji znajdziesz w artykule Konfigurowanie konta usługi.
- Pamiętaj, aby przesyłać pliki danych zbiorczych do środowiska, w którym pracujesz nad aktualizacjami w czasie rzeczywistym.
- Do uwierzytelniania interfejsu API zalecamy zainstalowanie biblioteki klienta Google w wybranym języku. Użyj zakresu protokołu OAuth „https://www.googleapis.com/auth/mapsbooking”. Przykłady kodu podane poniżej korzystają z tych bibliotek. W przeciwnym razie musisz ręcznie obsługiwać wymianę tokenów zgodnie z opisem w artykule Używanie OAuth 2.0 do korzystania z interfejsów API Google.
Konfigurowanie konta usługi
Aby wysyłać uwierzytelnione żądania HTTPS do interfejsów API Google, takich jak interfejs API aktualizacji w czasie rzeczywistym, musisz mieć konto usługi.
Aby skonfigurować konto usługi:
- Otwórz konsolę Google Cloud Platform.
- Twoje konto w Centrum działań jest też powiązane z projektem Google Cloud. Wybierz ten projekt, jeśli nie jest jeszcze wybrany.
- W menu po lewej stronie kliknij Konta usługi.
- Kliknij Utwórz konto usługi.
- Wpisz nazwę konta usługi i kliknij Utwórz.
- W sekcji Wybierz rolę kliknij Projekt > Edytujący.
- Kliknij Dalej.
- Opcjonalnie: dodaj użytkowników, aby przyznać im dostęp do konta usługi, i kliknij Gotowe.
- Kliknij więcej > Utwórz klucz w przypadku utworzonego właśnie konta usługi.
- Wybierz format JSON i kliknij Utwórz.
- Po wygenerowaniu nowej pary kluczy publicznych/prywatnych pobierz ją na swoje urządzenie.
Praca z interfejsem API
Interfejs Real-time updates API obsługuje 2 typy operacji: Update i Delete. Dodawanie nowych elementów za pomocą interfejsu API do aktualizacji w czasie rzeczywistym nie jest obsługiwane. Aktualizacje w czasie rzeczywistym można przesyłać w pakietach, jeśli w jednym żądaniu API uwzględnisz kilka aktualizacji. W jednym wywołaniu interfejsu API możesz przesłać zbiorczo do 1000 aktualizacji. Jeśli to możliwe, zalecamy stosowanie podejścia opartego na wyzwalaczach do wysyłania aktualizacji za pomocą RTU (tzn. po zmianie danych w systemie wywołaj aktualizację w czasie rzeczywistym w Google) zamiast podejścia opartego na częstotliwości (tzn. co X minut skanuj system pod kątem zmian).
Interfejs API aktualizacji w czasie rzeczywistym działa zarówno w piaskownicy, jak i w środowisku produkcyjnym. Środowisko piaskownicy służy do testowania żądań interfejsu API, a środowisko produkcyjne do aktualizowania treści widocznych dla użytkowników zamawiania zintegrowanego.
- Piaskownica –
partnerdev-mapsbooking.googleapis.com - Produkcja –
mapsbooking.googleapis.com
Punkty końcowe
Interfejs API aktualizacji w czasie rzeczywistym udostępnia 2 punkty końcowe do obsługi przychodzących żądań aktualizacji asortymentu:
- AKTUALIZACJA -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - USUŃ –
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
Parametr PARTNER_ID znajdziesz w Centrum działań na stronie Konto i użytkownicy, jak pokazano na zrzucie ekranu poniżej.
Na przykładzie z powyższego zrzutu ekranu, gdzie wartość PARTNER_ID to 10000001, pełne adresy URL do wysyłania żądań API w środowisku testowym i produkcyjnym będą wyglądać jak w przykładach poniżej.
Aktualizacja piaskownicy
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Usuwanie piaskownicy
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Aktualizacja wersji produkcyjnej
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Usuwanie wersji produkcyjnej
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Aktualizowanie elementów
Aby zaktualizować jednostki w swoim asortymencie, użyj punktu końcowego update w żądaniu HTTP POST. Każde żądanie POST musi zawierać parametr 10000001 oraz ładunek JSON zawierający podmiot, który chcesz zaktualizować.
Uwaga: upewnij się, że Twoje codzienne pliki danych zawierają też zmiany przesłane za pomocą interfejsu API do aktualizacji w czasie rzeczywistym. W przeciwnym razie dane mogą być nieaktualne.
Ładunek żądania aktualizacji
Treść żądania to obiekt JSON z listą rekordów. Każdy rekord odpowiada aktualizowanemu elementowi. Składa się z pola proto_record i pola generation_timestamp wskazującego czas aktualizacji elementu:
{
"records": [
{
"proto_record":"ServiceData PROTO",
"generation_timestamp":"UPDATE_TIMESTAMP"
}
]
}ServiceData PROTO: tłumaczenie w formacie proto lub JSON aktualizowanego przez Ciebie elementu ServiceData.UPDATE_TIMESTAMP: pamiętaj, aby w systemach backendu uwzględnić sygnaturę czasową wygenerowania elementu. Jeśli to pole nie zostanie uwzględnione, zostanie ustawione na czas, w którym Google otrzyma żądanie. Podczas aktualizowania elementu za pomocą żądaniabatchPushpolegeneration_timestampsłuży do określania wersji elementu. W schemacie relacyjnym asortymentu znajdziesz oczekiwany format wartości czasu.
- Rozmiar treści nie może przekraczać 5 MB.
- Usuń białe znaki, aby zmniejszyć rozmiar.
- W jednym żądaniu
batchPushmoże być maksymalnie 1000 aktualizacji.
Przykłady
Aktualizowanie rozszerzonej reklamy tekstowej
Załóżmy, że musisz pilnie zaktualizować szacowany czas dostawy z 30–60 minut na 60–90 minut. Aktualizacja musi zawierać kod JSON całej encji Service.
Weźmy pod uwagę encję usługi, która wygląda tak:
{ "service": { "service_id": "service/entity002", "service_type": "DELIVERY", "parent_entity_id": "entity002", "lead_time": { "min_lead_time_duration": "600s", "max_lead_time_duration": "1800s" }, "action_link_id": "delivery_link/entity002" } }
Aktualizacja w czasie rzeczywistym za pomocą żądania HTTP POST wygląda tak (treści żądań są sformatowane w celu zwiększenia czytelności):
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "3600" }, "max_lead_time_duration" : { "seconds": "5400" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }] }
Aktualizowanie wielu encji
Aby zaktualizować wiele obiektów restauracji w ramach jednego wywołania interfejsu API, w polu proto_record treści żądania umieść wiele rekordów.
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "1800" }, "max_lead_time_duration" : { "seconds": "3600" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee", "fee_type" : "DELIVERY", "fixed_amount" : { "currency_code" : "USD", "units" : "10", "nanos" : "0" }, "service_ids": ["service/entity002"] } }, "generation_timestamp" : "2023-09-13T17:11:10.750Z" }] }
Usuwanie encji
Aby usunąć jednostki z asortymentu, użyj punktu końcowego DELETE w żądaniu HTTP POST. Każde żądanie POST musi zawierać parametr PARTNER_ID oraz ładunek JSON, który zawiera identyfikator podmiotu, który chcesz usunąć.
Uwaga: upewnij się, że Twoje codzienne pliki danych zawierają też zmiany przesłane za pomocą interfejsu API do aktualizacji w czasie rzeczywistym. W przeciwnym razie codzienne przetwarzanie wsadowe nadpisze zmiany wprowadzone w czasie rzeczywistym.
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery" } }, "delete_time": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee" } }, "delete_time" : "2023-09-13T17:11:10.750Z" }] }
Dodawanie elementów
Nie używaj aktualizacji w czasie rzeczywistym do dodawania nowych elementów, ponieważ może to spowodować niespójności danych. Zamiast tego używaj plików danych zbiorczych.
Weryfikacja i kody odpowiedzi interfejsu API
W przypadku wywołań interfejsu API do aktualizacji w czasie rzeczywistym przeprowadzane są 2 rodzaje weryfikacji:
- Na poziomie żądania – te weryfikacje sprawdzają, czy ładunek jest zgodny ze schematem i czy każdy element
proto_recordzawiera polaiditype. Te weryfikacje są synchroniczne, a wyniki są zwracane w treści odpowiedzi interfejsu API. Kod odpowiedzi 200 i pusta treść JSON{}oznaczają, że te weryfikacje zostały zakończone pomyślnie, a encje w tym żądaniu zostały umieszczone w kolejce do przetworzenia. Kod odpowiedzi inny niż 200 oznacza, że co najmniej 1 z tych procesów weryfikacji nie powiódł się i całe żądanie zostało odrzucone (w tym wszystkie jednostki w ładunku). Jeśli na przykład w obiekcieproto_recordbrakuje elementu@type, zwracana jest ta odpowiedź o błędzie:
{ "error": { "code": 400, "message": "Record:{...}", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.DebugInfo", "detail": "[ORIGINAL ERROR] generic::invalid_argument: Failed to parse one or more rtu records. Record:... The entity type could not be extracted from the entity value." } ] }
- Na poziomie elementu: każdy element (proto_record) w ładunku jest weryfikowany pod kątem zgodności ze schematem. Problemy napotkane na tym etapie weryfikacji nie są zgłaszane w odpowiedzi interfejsu API. Są one raportowane tylko na panelu Raportowanie RTU w Centrum akcji.
Uwaga: kod odpowiedzi 200 nie oznacza, że wszystkie elementy zostały prawidłowo przetworzone.
Limity interfejsu API
Aktualizacje interfejsu API w czasie rzeczywistym mają limit 1500 żądań co 60 sekund, czyli średnio 25 żądań na sekundę. Gdy limit zostanie przekroczony, Google odpowie tym komunikatem o błędzie:
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}Aby temu zapobiec, ponawiaj wywołanie w coraz dłuższych odstępach czasu, aż się powiedzie. Jeśli regularnie wyczerpujesz limit, rozważ uwzględnienie większej liczby elementów w jednym żądaniu API. W jednym wywołaniu interfejsu API możesz uwzględnić maksymalnie 1000 elementów.
Aktualizacje w czasie rzeczywistym dotyczące czasu oczekiwania
Encja zaktualizowana w czasie rzeczywistym jest przetwarzana w ciągu 5 minut.