Reguły RTU są przeznaczone przede wszystkim dla aktualizacji, których nie można przewidzieć, takich jak zamknięcia awaryjne lub metadane zmieniające się okresowo (np. szacowany czas dotarcia na miejsce). Jeśli zmiana nie musi zostać uwzględniona natychmiast, możesz użyć przetwarzania zbiorczego pliku danych. Aktualizacje 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, potrzebny jest projekt GCP.
- Przyznaj dostęp edytującym food-support@google.com
- Poinformuj osobę kontaktową w Google o numerze projektu GCP.Aby aktualizacje w czasie rzeczywistym działały, Twój projekt GCP musi być powiązany z kontem Actions Center.
- Włącz interfejs Maps Booking API:
- W GCP otwórz Interfejsy API 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 przypisaną rolą edytującego projekt GCP. Więcej informacji znajdziesz w artykule Konfigurowanie konta usługi.
- Pamiętaj, aby przesłać wsadowe pliki danych do środowiska, w którym pracujesz nad aktualizacjami w czasie rzeczywistym.
- Na potrzeby uwierzytelniania w ramach interfejsu API zalecamy zainstalowanie biblioteki klienta Google w wybranym języku. Używaj „https://www.googleapis.com/auth/mapsbooking” jako zakresu protokołu OAuth. Wymienione poniżej przykładowe fragmenty kodu korzystają z tych bibliotek. W przeciwnym razie musisz ręcznie obsługiwać wymianę tokenów zgodnie z opisem w artykule Uzyskiwanie dostępu do interfejsów API Google przy użyciu OAuth 2.0.
Konfigurowanie konta usługi
Aby wysyłać uwierzytelnione żądania HTTPS do interfejsów API 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 menu Wybierz rolę kliknij Projekt > .
- 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 przed chwilą konta usługi.
- Wybierz format JSON i kliknij Utwórz.
- Po wygenerowaniu nowej pary kluczy publiczny/prywatny pobierz ją na swój komputer.
Praca z interfejsem API
Interfejs API aktualizacji w czasie rzeczywistym obsługuje 2 typy operacji: aktualizowanie i usuwanie. Dodawanie nowych elementów za pomocą interfejsu API aktualizacji w czasie rzeczywistym nie jest obsługiwane. Aktualizacje w czasie rzeczywistym mogą być grupowane, jeśli w jednym żądaniu do interfejsu API zawrzesz wiele aktualizacji. W jednym wywołaniu interfejsu API możesz zgrupować maksymalnie 1000 aktualizacji. W miarę możliwości zalecamy stosowanie metody opartej na aktywatorach, która służy do wysyłania aktualizacji przez RTU (tzn. gdy zmiana danych w systemie powoduje uruchomienie aktualizacji do Google w czasie rzeczywistym), a nie częstotliwość (czyli co X minut skanowanie systemu pod kątem zmian).
Interfejs API aktualizacji w czasie rzeczywistym działa zarówno w środowisku piaskownicy, jak i w środowisku produkcyjnym. Środowisko piaskownicy służy do testowania żądań do interfejsu API i w środowisku produkcyjnym w celu aktualizowania treści widocznych dla użytkowników korzystających z usługi zamawiania.
- 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 zasobów:
- AKTUALIZUJ –
/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 widać na zrzucie ekranu poniżej.
Przyjmując 10000001 jako wartość identyfikatora PARTNER_ID jak na zrzucie ekranu powyżej, pełne adresy URL do wysyłania żądań do interfejsu API w trybie piaskownicy i w środowisku produkcyjnym będą wyglądać tak jak w przykładach poniżej.
Aktualizacja piaskownicy
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
USUŃ w trybie 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
DELETE produkcyjne
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Aktualizuję elementy
Aby zaktualizować elementy 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: dopilnuj, aby codzienne pliki danych zawierały też zmiany przesłane za pomocą interfejsu API aktualizacji w czasie rzeczywistym. W przeciwnym razie dane mogą być nieaktualne.
Zaktualizuj ładunek żądania
Treść żądania to obiekt JSON z listą rekordów. Każdy rekord odpowiada aktualizowanej encji. Składa się z pola proto_record i elementu generation_timestamp, które wskazuje czas aktualizacji elementu:
{
"records": [
{
"proto_record":"ServiceData PROTO",
"generation_timestamp":"UPDATE_TIMESTAMP"
}
]
}
ServiceData PROTO: translacja proto lub JSON aktualizowanej encji ServiceData.UPDATE_TIMESTAMP: pamiętaj, aby podać sygnaturę czasową określającą, kiedy element został wygenerowany w systemach backendu. Jeśli to pole nie zostanie uwzględnione, zostanie ustawione na dzień, w którym Google otrzyma żądanie. Podczas aktualizowania elementu za pomocą żądaniabatchPushpolegeneration_timestampjest używane do obsługi wersji elementu. Sprawdź oczekiwany format wartości czasowych w schemacie relacyjnych zasobów reklamowych.
- Treść ł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 na miejsce
Załóżmy, że chcesz pilnie zaktualizować szacowany czas dotarcia na miejsce w usłudze dostawy z 30–60 do 60–90 minut. Aktualizacja musi zawierać kod JSON dla całej encji Service.
Weźmy pod uwagę jednostkę 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 metodą POST w odpowiedzi HTTP wygląda tak (treść żądania jest wydrukowana, aby zwiększyć czytelność):
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 w 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 encji, którą chcesz usunąć.
Uwaga: dopilnuj, aby codzienne pliki danych zawierały też zmiany przesłane za pomocą interfejsu API aktualizacji w czasie rzeczywistym. W przeciwnym razie codzienne przetwarzanie zbiorcze zastąpi 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 encji
Nie dodawaj nowych elementów w czasie rzeczywistym, ponieważ może to doprowadzić do niespójności danych. Zamiast tego użyj plików wsadowych.
Weryfikacja Kody odpowiedzi interfejsu API
W przypadku wywołań interfejsu API aktualizacji w czasie rzeczywistym wykonywane są 2 typy 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{}oznaczają, że weryfikacja przebiegła pomyślnie, a encje w danym żą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 i całe żądanie (łącznie ze wszystkimi elementami w ładunku). Jeśli na przykład w poluproto_recordbrakuje parametru@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."
}
]
}
- Poziom encji: każda encja (proto_record) w ładunku jest weryfikowana według schematu. Problemy, które wystąpiły na tej fazie weryfikacji, nie są zgłaszane w odpowiedzi interfejsu API. Są one widoczne tylko w panelu Raportowanie RTU w Centrum działań.
Uwaga: kod odpowiedzi 200 nie oznacza, że wszystkie elementy zostały pozyskane.
Limity interfejsu API
Aktualizacje interfejsu API w czasie rzeczywistym mają limit 1500 żądań co 60 sekund, czyli średnio 25 żądań na sekundę. W przypadku przekroczenia limitu Google w odpowiedzi przesyła następujący komunikat o błędzie:
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}
Aby to zrobić, ponawiaj próby w znacznie 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. Jedno wywołanie interfejsu API może zawierać do 1000 elementów.
Czasy przetwarzania aktualizacji w czasie rzeczywistym
Encja zaktualizowana za pomocą aktualizacji w czasie rzeczywistym jest przetwarzana w ciągu 5 minut.