RTU są przeznaczone przede wszystkim do przesyłania aktualizacji, których nie można przewidzieć, takich jak zamknięcia awaryjne czy metadane, które zmieniają się okresowo (np. szacowany czas dotarcia na miejsce). Jeśli zmiana nie musi zostać uwzględniona natychmiast, możesz skorzystać z przetwarzania wsadowego pliku danych. Dane aktualizowane w czasie rzeczywistym są przetwarzane nie dłużej niż 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 Centrum akcji.
- Włącz interfejs API rezerwacji w Mapach Google:
- W GCP kliknij Interfejsy API i usługi > Biblioteka.
- Wyszukaj „Google Maps Booking API”.
- Odszukaj 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 przesłać zbiorcze pliki danych do środowiska, w którym pracujesz nad aktualizacjami w czasie rzeczywistym.
- Na potrzeby uwierzytelniania interfejsu API zalecamy zainstalowanie biblioteki klienta Google w wybranym języku. Użyj zakresu OAuth „https://www.googleapis.com/auth/mapsbooking”. Przykładowe fragmenty kodu, które widzisz poniżej, korzystają z tych bibliotek. W przeciwnym razie wymiana tokenów musi być obsługiwana ręcznie zgodnie z opisem w artykule Korzystanie z protokołu 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 API Google, na przykład do interfejsu API aktualizacji w czasie rzeczywistym, musisz mieć konto usługi.
Aby skonfigurować konto usługi, wykonaj te czynności:
- Otwórz konsolę Google Cloud Platform.
- Z Twoim kontem w Actions Center jest też powiązany projekt Google Cloud. Wybierz projekt, jeśli nie jest jeszcze wybrany.
- Kliknij Konta usługi w menu po lewej stronie.
- 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.
- Dla utworzonego konta usługi kliknij Więcej > Utwórz klucz.
- Wybierz format JSON i kliknij Utwórz.
- Po wygenerowaniu nowej pary kluczy (publicznego/prywatnego) pobierz ją na swój komputer.
Praca z interfejsem API
Interfejs API aktualizacji w czasie rzeczywistym obsługuje 2 rodzaje operacji: aktualizowanie i usuwanie. Dodawanie nowych encji za pomocą interfejsu API aktualizacji w czasie rzeczywistym nie jest obsługiwane. Jeśli dodasz wiele aktualizacji w jednym żądaniu do interfejsu API, aktualizacje w czasie rzeczywistym mogą być grupowane. W jednym wywołaniu interfejsu API możesz zgrupować maksymalnie 1000 aktualizacji. Zalecamy stosowanie metody opartej na aktywatorach przy wysyłaniu aktualizacji przez RTU (tj. gdy zmiana danych w systemie uruchamia aktualizację do Google w czasie rzeczywistym), a nie na podstawie częstotliwości (tj. co X minut skanowania systemu pod kątem zmian).
Interfejs API aktualizacji w czasie rzeczywistym działa zarówno w środowisku piaskownicy, jak i środowisku produkcyjnego. Środowisko piaskownicy służy do testowania żądań do interfejsu API i środowiska produkcyjnego w celu aktualizowania treści widocznej dla użytkowników kompleksowych zamówień.
- Piaskownica –
partnerdev-mapsbooking.googleapis.com - Produkcyjna –
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 zasobów reklamowych:
- 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 można znaleźć w Centrum działań na stronie Konto i użytkownicy, jak widać na zrzucie ekranu poniżej.
Jeśli weźmiemy 10000001 jako wartość identyfikatora PARTNER_ID z powyższego zrzutu ekranu, pełne adresy URL do wysyłania żądań do interfejsu API w piaskownicy i środowisku produkcyjnym będą wyglądać jak w poniższych przykładach.
Aktualizacja piaskownicy
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
USUŃ Z Piaskownicy
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Aktualizacja produkcyjna
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Usunięcie wersji produkcyjnej
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Aktualizuję elementy
Aby zaktualizować encje w zasobach reklamowych, użyj punktu końcowego update w żądaniu HTTP POST. Każde żądanie POST musi zawierać parametr 10000001 wraz z ładunkiem JSON zawierającym encję, którą chcesz zaktualizować.
Uwaga: upewnij się, że Twoje codzienne pliki danych zawierają też wszelkie zmiany przesłane za pomocą interfejsu API aktualizacji w czasie rzeczywistym. Jeśli tego nie zrobisz, Twoje dane mogą być nieaktualne lub nieaktualne.
Zaktualizuj ładunek żądania
Treść żądania to obiekt JSON z listą rekordów. Każdy rekord odpowiada aktualizowanym elementom. Składa się z pola proto_record i pola generation_timestamp wskazującego godzinę aktualizacji elementu:
{
"records": [
{
"proto_record":"ServiceData PROTO",
"generation_timestamp":"UPDATE_TIMESTAMP"
}
]
}
ServiceData PROTO: translacja proto lub JSON encji ServiceData, którą aktualizujesz.UPDATE_TIMESTAMP: pamiętaj, by podać sygnaturę czasową momentu wygenerowania elementu w systemach backendu. Jeśli to pole nie zostanie podane, w polu pojawi się data otrzymania żądania przez Google. Gdy aktualizujesz encję za pomocą żądaniabatchPush, do obsługi wersji elementu używane jest polegeneration_timestamp. Sprawdź oczekiwany format wartości czasowych w schemacie relacyjnych zasobów reklamowych.
- Rozmiar treści ładunku nie może przekraczać 5 MB.
- Usuń spacje, aby zmniejszyć rozmiar.
- Żądanie
batchPushmoże zawierać maksymalnie 1000 aktualizacji.
Przykłady
Zaktualizuj szacowany czas dotarcia
Załóżmy, że musisz pilnie zaktualizować szacowany czas dotarcia na miejsce w usłudze dostawy z 30–60 na 60–90 minut. Aktualizacja musi zawierać kod JSON dla całej encji Service.
Weźmy np. taki podmiot usługowy:
{
"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ą metody POST w protokole HTTP (treść żądań jest dość wydrukowana), aby ułatwić czytanie:
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, umieść wiele rekordów w polu proto_record treści żą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"
}]
}
Usuń elementy
Aby usunąć encje z zasobów reklamowych, użyj punktu końcowego DELETE w żądaniu HTTP POST. Każde żądanie POST musi zawierać parametr PARTNER_ID wraz z ładunkiem JSON zawierającym identyfikator jednostki, którą chcesz usunąć.
Uwaga: upewnij się, że Twoje codzienne pliki danych zawierają też wszelkie zmiany przesłane za pomocą interfejsu API aktualizacji w czasie rzeczywistym. W przeciwnym razie dzienne przetwarzanie zbiorcze zastąpi 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 jednostek
Nie używaj aktualizacji w czasie rzeczywistym do dodawania nowych elementów, ponieważ może to spowodować niespójności w danych. Zamiast tego używaj zbiorczych plików danych.
Kody weryfikacyjne i kody odpowiedzi interfejsu API
Wywołania interfejsu API aktualizacji w czasie rzeczywistym podlegają 2 rodzajom weryfikacji:
- Poziom żądania – weryfikacje sprawdzają, czy ładunek jest zgodny ze schematem, a każdy element
proto_recordzawiera polaiditype. Te kontrole są synchroniczne, a wyniki są zwracane w treści odpowiedzi interfejsu API. Kod odpowiedzi 200 i pusta treść JSON{}oznacza, że weryfikację przebiegło pomyślnie, a encje w żądaniu zostały umieszczone w kolejce do przetworzenia. Kod odpowiedzi inny niż 200 oznacza, że co najmniej jedna z tych weryfikacji zakończyła się niepowodzeniem, a całe żądanie zostało odrzucone (łącznie ze wszystkimi elementami w ładunku). Jeśli na przykład w elemencieproto_recordbrakuje wartości@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 jednostki: każda encja (proto_record) w ładunku jest sprawdzana pod kątem schematu. Problemy napotkane na tym etapie weryfikacji nie są zgłaszane w odpowiedzi interfejsu API. Są one dostępne tylko w panelu Raportowanie czasu rzeczywistego w Actions Center.
Uwaga: kod odpowiedzi 200 nie oznacza, że wszystkie encje zostały przetworzone.
Limity interfejsu API
W przypadku aktualizacji interfejsu API w czasie rzeczywistym obowiązuje limit 1500 żądań na 60 sekund lub średnio 25 żądań na sekundę. Po przekroczeniu limitu Google wyświetla komunikat o błędzie:
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}
Aby rozwiązać ten problem, ponawiaj próbę wywołania w wykładniczo większych odstępach czasu, aż się uda. Jeśli regularnie wyczerpujesz limit, rozważ uwzględnienie większej liczby encji w jednym żądaniu do interfejsu API. W jednym wywołaniu interfejsu API możesz uwzględnić maksymalnie 1000 encji.
Aktualizacje w czasie rzeczywistym dotyczące czasu przetwarzania
Encja zaktualizowana przy użyciu aktualizacji w czasie rzeczywistym jest przetwarzana w ciągu 5 minut.