Gli aggiornamenti in tempo reale sono pensati principalmente per aggiornamenti che non puoi prevedere, come chiusure di emergenza o metadati che cambiano periodicamente (come gli orari di arrivo stimati). Se la modifica non deve essere applicata immediatamente, puoi utilizzare l'importazione batch dei feed. Gli aggiornamenti in tempo reale vengono elaborati in non più di cinque minuti.
Configurazione di Google Cloud Platform
- Configura un progetto GCP. Per accedere all'API RTU è necessario un progetto Google Cloud.
- Concedi l'accesso come editor a food-support@google.com
- Comunica al tuo contatto Google il numero del progetto GCP.Per consentire gli aggiornamenti in tempo reale, il progetto GCP deve essere associato al tuo account Centro azioni.
- Abilita l'API Maps Booking:
- In GCP, vai ad API e servizi > Libreria.
- Cerca "API Google Maps Booking".
- Trova l'istanza Sandbox ("API Google Maps Booking (Dev)") e fai clic su Abilita.
- Trova l'istanza di produzione ("API Google Maps Booking") e fai clic su Abilita
- Crea un service account con un ruolo di editor per il tuo progetto Google Cloud. Per maggiori dettagli, vedi Configurazione del service account.
- Assicurati di caricare i feed batch nell'ambiente in cui stai lavorando agli aggiornamenti in tempo reale.
- Per l'autenticazione API, ti consigliamo di installare la libreria client di Google nella lingua che preferisci. Utilizza "https://www.googleapis.com/auth/mapsbooking" come ambito OAuth. Gli esempi di codice inclusi di seguito utilizzano queste librerie. In caso contrario, dovrai gestire manualmente gli scambi di token, come descritto in Utilizzare OAuth 2.0 per accedere alle API di Google.
Configurazione dell'account di servizio
Per effettuare richieste HTTPS autenticate alle API di Google, ad esempio l'API per gli aggiornamenti in tempo reale, devi disporre di un service account.
Per configurare un service account:
- Accedi alla console Google Cloud Platform.
- Anche il tuo account sul Centro azioni ha un progetto Google Cloud associato. Seleziona il progetto, se non è già selezionato.
- Fai clic su Account di servizio nel menu a sinistra.
- Fai clic su Crea service account.
- Inserisci un nome per l'account di servizio e fai clic su Crea.
- In Seleziona un ruolo, scegli Progetto > Editor.
- Fai clic su Continua.
- (Facoltativo) Aggiungi utenti per concedere loro l'accesso al service account e fai clic su Fine.
- Fai clic su Altro > Crea chiave per il service account che hai appena creato.
- Seleziona JSON come formato e fai clic su Crea.
- Dopo aver generato la nuova coppia di chiavi pubblica/privata, scaricala sul tuo computer.
Utilizzo dell'API
L'API Realtime Updates supporta due tipi di operazioni: aggiornamento ed eliminazione. L'aggiunta di nuove entità tramite l'API di aggiornamento in tempo reale non è supportata. Gli aggiornamenti in tempo reale possono essere raggruppati in batch se includi più aggiornamenti in un'unica richiesta API. Puoi raggruppare fino a 1000 aggiornamenti in una singola chiamata API. Se possibile, ti consigliamo di utilizzare un approccio basato su trigger per inviare aggiornamenti tramite RTU (ovvero, quando i dati cambiano nel tuo sistema, viene attivato un aggiornamento in tempo reale a Google) anziché un approccio basato sulla frequenza (ovvero, ogni X minuti il sistema viene analizzato per rilevare modifiche).
L'API per gli aggiornamenti in tempo reale funziona sia in ambienti sandbox che di produzione. L'ambiente sandbox viene utilizzato per testare le richieste API e l'ambiente di produzione per aggiornare i contenuti visibili agli utenti di Ordering End-to-End.
- Sandbox -
partnerdev-mapsbooking.googleapis.com - Produzione -
mapsbooking.googleapis.com
Endpoint
L'API per gli aggiornamenti in tempo reale espone due endpoint per gestire le richieste in entrata per gli aggiornamenti dell'inventario:
- AGGIORNAMENTO -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - ELIMINA -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
Il parametro PARTNER_ID è disponibile in Actions Center nella pagina Account e utenti, come mostrato nello screenshot di seguito.
Prendendo 10000001 come valore di PARTNER_ID come esempio dallo screenshot precedente, gli URL completi per l'invio di richieste API in sandbox e produzione saranno simili a quelli riportati negli esempi di seguito.
Aggiornamento della sandbox
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Sandbox DELETE
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Aggiornamento sulla produzione
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Eliminazione della produzione
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Aggiornamento delle entità
Per aggiornare le entità nell'inventario, utilizza l'endpoint update in una richiesta POST HTTP. Ogni richiesta POST deve includere il parametro 10000001 insieme a un payload JSON contenente l'entità che vuoi aggiornare.
Nota:assicurati che i feed di dati giornalieri contengano anche le modifiche inviate tramite l'API di aggiornamenti in tempo reale. In caso contrario, i dati potrebbero essere obsoleti.
Aggiorna il payload della richiesta
Il corpo della richiesta è un oggetto JSON con un elenco di record. Ogni record corrisponde a un'entità in fase di aggiornamento. È composto dal campo proto_record e dal campo generation_timestamp che indica l'ora dell'aggiornamento dell'entità:
{
"records": [
{
"proto_record":"ServiceData PROTO",
"generation_timestamp":"UPDATE_TIMESTAMP"
}
]
}ServiceData PROTO: la traduzione proto o JSON dell'entità ServiceData che stai aggiornando.UPDATE_TIMESTAMP: assicurati di includere il timestamp di generazione dell'entità nei tuoi sistemi di backend. Se questo campo non è incluso, verrà impostato sull'ora in cui Google riceve la richiesta. Quando aggiorni un'entità tramite una richiestabatchPush, il campogeneration_timestampviene utilizzato per il controllo delle versioni dell'entità. Consulta il formato previsto dei valori temporali nello schema dell'inventario relazionale.
- Le dimensioni del corpo del payload non devono superare i 5 MB.
- Rimuovi gli spazi bianchi per ridurre le dimensioni.
- Una richiesta
batchPushpuò contenere fino a 1000 aggiornamenti.
Esempi
Aggiornare un orario di arrivo stimato
Supponiamo che tu abbia urgente bisogno di aggiornare l'ETA di un servizio di consegna da 30-60 a 60-90 minuti. L'aggiornamento deve contenere il JSON per l'intera entità Service.
Considera un'entità di servizio simile alla seguente:
{ "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" } }
L'aggiornamento in tempo reale tramite HTTP POST è il seguente (i corpi delle richieste sono stampati in modo leggibile):
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" }] }
Aggiornare più entità
Per aggiornare più entità ristorante in una singola chiamata API, includi più record nel campo proto_record del corpo della richiesta.
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" }] }
Elimina entità
Per eliminare le entità dall'inventario, utilizza l'endpoint DELETE in una richiesta POST HTTP. Ogni richiesta POST deve includere il parametro PARTNER_ID insieme al payload JSON che contiene l'identificatore dell'entità che vuoi eliminare.
Nota:assicurati che i feed di dati giornalieri contengano anche le modifiche inviate tramite l'API di aggiornamento in tempo reale. In caso contrario, l'importazione batch giornaliera sovrascriverà le modifiche in tempo reale.
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" }] }
Aggiunta di entità
Non utilizzare gli aggiornamenti in tempo reale per aggiungere nuove entità, in quanto ciò potrebbe causare incoerenze nei dati. Utilizza invece i feed batch.
Codici di risposta dell'API e convalida
Esistono due tipi di convalide eseguite sulle chiamate API di aggiornamento in tempo reale:
- A livello di richiesta: queste convalide verificano che il payload segua lo schema e che ogni
proto_recordcontenga i campiidetype. Questi controlli sono sincroni e i risultati vengono restituiti nel corpo della risposta dell'API. Un codice di risposta 200 e un corpo JSON vuoto{}indicano che queste convalide sono state superate e che le entità nella richiesta sono state inserite in coda per l'elaborazione. Un codice di risposta diverso da 200 indica che una o più di queste convalide non sono riuscite e l'intera richiesta viene rifiutata (incluse tutte le entità nel payload). Ad esempio, se a unproto_recordmanca un@type, viene restituita la seguente risposta di errore:
{ "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." } ] }
- A livello di entità: ogni entità (proto_record) nel payload viene convalidata in base allo schema. I problemi riscontrati in questa fase di convalida non vengono segnalati nella risposta dell'API. Vengono segnalati solo nella dashboard Report RTU del Centro azioni.
Nota:un codice di risposta 200 non significa che tutte le entità sono state inserite correttamente.
Quote API
Gli aggiornamenti API in tempo reale hanno una quota di 1500 richieste ogni 60 secondi, ovvero 25 richieste al secondo in media. Quando una quota viene superata, Google risponde con il seguente messaggio di errore:
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}Per gestire questo problema, riprova la chiamata a intervalli esponenzialmente più grandi finché non va a buon fine. Se esaurisci regolarmente la quota, valuta la possibilità di includere più entità in una richiesta API. Puoi includere fino a 1000 entità in una chiamata API.
Aggiornamenti in tempo reale sui tempi di elaborazione
Un'entità aggiornata tramite un aggiornamento in tempo reale viene elaborata in 5 minuti.