RTU są przeznaczone przede wszystkim do aktualizacji, których nie można przewidzieć, takich jak nagłe zamknięcia lub metadane, które zmieniają się okresowo (np. ETA). Jeśli zmiana nie musi być odzwierciedlona natychmiast, możesz użyć zbiorczego przetwarzania pliku danych. Aktualizacje w czasie rzeczywistym są przetwarzane w ciągu maksymalnie 5 minut.
Konfiguracja Google Cloud Platform
- skonfigurować projekt GCP, Dostęp do interfejsu RTU API wymaga projektu GCP.
- Przyznaj dostęp do edytora adresowi food-support@google.com .
- Poinformuj osobę kontaktową z Google o numerze projektu GCP.Aby aktualizacje w czasie rzeczywistym działały, projekt GCP musi być powiązany z Twoim kontem Centrum działań.
- Włącz interfejs API Rezerwacji w Mapach Google:
- 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 konto usługi z rolą edytującego w projekcie GCP. 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 w interfejsie API zalecamy zainstalowanie biblioteki klienta Google w wybranym języku. Jako zakres protokołu OAuth użyj adresu „https://www.googleapis.com/auth/mapsbooking”. Poniżej znajdziesz przykłady kodu, które korzystają z tych bibliotek. W przeciwnym razie musisz ręcznie przeprowadzić wymianę tokenów zgodnie z opisem w artykule Używanie OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google.
Konfigurowanie konta usługi
Aby wysyłać uwierzytelnione żądania HTTPS do interfejsów Google, takich jak interfejs API aktualizacji w czasie rzeczywistym, potrzebujesz konta usługi.
Aby skonfigurować konto usługi:
- Otwórz konsolę Google Cloud Platform.
- Z Twoim kontem w Centrum działań jest też powiązany projekt 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 dla utworzonego właśnie konta usługi.
- Jako format wybierz JSON i kliknij Utwórz.
- Po wygenerowaniu nowej pary kluczy publicznych/prywatnych pobierz ją na swoje urządzenie.
Praca z interfejsem API
Interfejs API aktualizacji w czasie rzeczywistym 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 grupować, jeśli w pojedynczym żądaniu interfejsu API uwzględnisz wiele aktualizacji. W jednym wywołaniu interfejsu API możesz zbiorczo przesłać do 1000 aktualizacji. Zalecamy, aby w miarę możliwości korzystać z metody wysyłania aktualizacji za pomocą RTU (czyli po zmianie danych w systemie uruchamiać aktualizację w czasie rzeczywistym) zamiast metody o konkretnej częstotliwości (czyli co X minut sprawdzać system pod kątem zmian).
Interfejs API aktualizacji w czasie rzeczywistym działa zarówno w środowisku piaskownicy, jak i w środowisku produkcyjnym. Piaskownica służy do testowania żądań interfejsu API, a środowisko produkcyjne do aktualizowania treści widocznych dla użytkowników usługi Zamów wszystko.
- 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ń dotyczących aktualizacji asortymentu:
- AKTUALIZACJA –
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - DELETE -
/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 zrzutu ekranu powyżej, w którym wartość parametru PARTNER_ID to 10000001, pełne adresy URL wysyłania żądań interfejsu API w sandbox i produkcji 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
USUŃ piaskownicę
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
USUŃ w wersji produkcyjnej
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Aktualizuję elementy
Aby zaktualizować elementy 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 element, który chcesz zaktualizować.
Uwaga: sprawdź, czy codzienne pliki danych zawierają wszystkie zmiany przesłane za pomocą interfejsu API do aktualizacji w czasie rzeczywistym. W przeciwnym razie dane mogą być nieaktualne lub nieaktualne.
Ładunek żądania aktualizacji
Treść żądania to obiekt JSON z listą rekordów. Każdy rekord odpowiada aktualizowanemu elementowi. Zawiera ono pole proto_record i pole generation_timestamp wskazujące czas aktualizacji elementu:
{
"records": [
{
"proto_record":"ServiceData PROTO",
"generation_timestamp":"UPDATE_TIMESTAMP"
}
]
}ServiceData PROTO: prototyp lub tłumaczenie w formacie JSON obiektu ServiceData, który aktualizujesz.UPDATE_TIMESTAMP: pamiętaj, aby podać sygnaturę czasową wygenerowania elementu w systemach backendu. Jeśli to pole nie zostanie wypełnione, zostanie ustawiona godzina, o której Google otrzyma prośbę. Podczas aktualizowania elementu za pomocą żądaniabatchPushpolegeneration_timestampjest używane do wersji elementu. Sprawdź oczekiwany format wartości czasu w relacyjnej strukturze asortymentu.
- Rozmiar treści ładunku nie może przekraczać 5 MB.
- Usuń spacje, aby zmniejszyć rozmiar.
- W żądaniu
batchPushmoże być maksymalnie 1000 aktualizacji.
Przykłady
Aktualizowanie szacowanego czasu dotarcia
Załóżmy, że musisz pilnie zaktualizować szacowany czas dostawy z 30–60 minut na 60–90 minut. Aktualizacja musi zawierać dane w formacie JSON dotyczące całej usługi.
Weź pod uwagę element usługi, który 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 (w celu ułatwienia odczytu treść żądania jest ładnie wydrukowana):
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 elementów
Aby zaktualizować wiele elementów restauracji w jednym wywołaniu interfejsu API, dodaj wiele rekordów w polu proto_record w ciele żądania.
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ąć elementy z swojego asortymentu, użyj punktu końcowego DELETE w żądaniu HTTP POST. Każde żądanie POST musi zawierać parametr PARTNER_ID wraz z danymi w formacie JSON, które zawierają identyfikator zasobu, który chcesz usunąć.
Uwaga: sprawdź, czy codzienne pliki danych zawierają wszystkie zmiany przesłane za pomocą interfejsu API do aktualizacji w czasie rzeczywistym. W przeciwnym razie codzienne przetwarzanie zbiorcze zastąpi Twoje zmiany 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żyj plików danych zbiorczych.
Kody odpowiedzi weryfikacji i interfejsu API
W przypadku wywołań interfejsu API służących do aktualizacji w czasie rzeczywistym przeprowadzane są 2 typy weryfikacji:
- Na poziomie żądania – te weryfikacje sprawdzają, czy ładunek jest zgodny ze schematem i czy każde
proto_recordzawiera polaiditype. Te weryfikacje są synchroniczne, a ich wyniki są zwracane w ciele odpowiedzi interfejsu API. Kod odpowiedzi 200 i puste ciało JSON{}oznaczają, że te weryfikacje zostały pomyślnie przeprowadzone, a elementy w tym żądaniu zostały umieszczone w kolejce do przetwarzania. Kod odpowiedzi inny niż 200 oznacza, że co najmniej 1 z tych weryfikacji nie powiodła się i cała prośba została odrzucona (w tym wszystkie elementy w ładunku). Jeśli na przykład w elementachproto_recordbrakuje elementu@type, zwracana jest taka odpowiedź z błędem:
{ "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żda entencja (proto_record) w ładunku jest weryfikowana pod kątem schematu. Problemy napotkane na tym etapie weryfikacji nie są zgłaszane w odpowiedzi interfejsu API. Są one raportowane tylko na karcie Raportowanie RTU w Centrum działań.
Uwaga: kod odpowiedzi 200 nie oznacza, że wszystkie elementy zostały pobrane.
Limity interfejsu API
Limit interfejsu API w czasie rzeczywistym wynosi 1500 żądań co 60 sekund, czyli średnio 25 żądań na sekundę. Gdy przekroczysz limit, Google odpowie komunikatem o błędzie:
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}Aby temu zaradzić, powtarzaj wywołanie z coraz większymi odstępami czasowymi, aż się powiedzie. Jeśli regularnie wyczerpujesz limit, rozważ uwzględnienie większej liczby elementów w jednym żądaniu interfejsu API. W jednym wywołaniu interfejsu API możesz uwzględnić maksymalnie 1000 elementów.
Aktualizacje w czasie rzeczywistym dotyczące czasu przetwarzania
Obiekt zaktualizowany w czasie rzeczywistym jest przetwarzany przez 5 minut.