Le RTU sono destinate principalmente agli aggiornamenti che non puoi prevedere, come le chiusure per emergenze o i metadati che cambiano periodicamente (ad esempio le stime di arrivo). Se la modifica non deve essere applicata immediatamente, puoi utilizzare l'importazione collettiva dei feed. Gli aggiornamenti in tempo reale vengono elaborati in non più di cinque minuti.
Configurazione della piattaforma Google Cloud
- Configura un progetto Google Cloud. Per accedere all'API RTU è necessario un progetto Google Cloud.
- Concedi l'accesso all'editor food-support@google.com
- Comunica al tuo POC Google il numero del progetto Google Cloud.Affinché gli aggiornamenti in tempo reale funzionino, il progetto Google Cloud deve essere associato al tuo account Centro azioni.
- Abilita l'API Maps Booking:
- In Google Cloud, vai ad API e servizi > Libreria.
- Cerca "API Google Maps Booking".
- Individua l'istanza Sandbox ("API Google Maps Booking (Dev)") e fai clic su Attiva.
- Individua l'istanza di produzione ("API Google Maps Booking") e fai clic su Attiva.
- Crea un account di servizio con il ruolo di editor per il tuo progetto Google Cloud. Per maggiori dettagli, vedi Configurazione dell'account di servizio.
- Assicurati di caricare i feed batch nell'ambiente in cui stai lavorando per gli aggiornamenti in tempo reale.
- Per l'autenticazione API, ti consigliamo di installare la libreria client 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 di aggiornamenti in tempo reale, è necessario un account di servizio.
Per configurare un account di servizio:
- Accedi alla console della piattaforma Google Cloud.
- Al tuo account nel Centro azioni è associato anche un progetto Google Cloud. Seleziona il progetto, se non è già selezionato.
- Fai clic su Account di servizio nel menu a sinistra.
- Fai clic su Crea account di servizio.
- 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 gli utenti a cui concedere l'accesso all'account di servizio e fai clic su Fine.
- Fai clic su Altro > Crea chiave per l'account di servizio 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 Aggiornamenti in tempo reale 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 se includi più aggiornamenti in una singola 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 attivare un aggiornamento in tempo reale su Google in caso di modifica dei dati nel sistema) anziché un approccio basato sulla frequenza (ovvero eseguire la scansione del sistema per rilevare le modifiche ogni X minuti).
L'API di aggiornamento in tempo reale opera sia in ambienti sandbox che di produzione. L'ambiente sandbox viene utilizzato per testare le richieste dell'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 di aggiornamento 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 - DELETE -
/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 sopra, gli URL completi per l'invio di richieste API in sandbox e in produzione saranno come negli esempi riportati 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
PRODUZIONE DELETE
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Aggiornamento delle entità
Per aggiornare le entità nel tuo 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à da aggiornare.
Nota:assicurati che i feed di dati giornalieri contengano anche eventuali modifiche inviate tramite l'API di aggiornamenti in tempo reale. In caso contrario, i dati potrebbero essere obsoleti o non aggiornati.
Payload della richiesta di aggiornamento
Il corpo della richiesta è un oggetto JSON con un elenco di record. Ogni record corrisponde a un'entità da aggiornare. È costituito 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 in proto o JSON dell'entità ServiceData che stai aggiornando.UPDATE_TIMESTAMP: assicurati di includere il timestamp dell'ora in cui l'entità è stata generata nei tuoi sistemi di backend. Se questo campo non è incluso, verrà impostato sull'ora in cui Google riceve la richiesta. Quando viene aggiornata un'entità tramite una richiestabatchPush, il campogeneration_timestampviene utilizzato per il controllo delle versioni delle entità. Consulta il formato previsto per i valori di tempo nello schema di inventario relazionale.
- Il corpo del payload non deve superare i 5 MB.
- Rimuovi gli spazi vuoti per ridurre le dimensioni.
- Una richiesta
batchPushpuò contenere fino a 1000 aggiornamenti.
Esempi
Aggiornare un orario di arrivo stimato
Supponiamo che tu debba aggiornare urgentemente l'orario di arrivo stimato 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 che ha il seguente aspetto:
{ "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 POST HTTP è il seguente (i corpi delle richieste sono stampati in modo leggibile per una maggiore chiarezza):
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à di ristoranti 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" }] }
Eliminare le entità
Per eliminare le entità dal tuo inventario, utilizza l'endpoint DELETE in una richiesta POST HTTP. Ogni richiesta POST deve includere il parametro PARTNER_ID insieme al payload JSON contenente l'identificatore dell'entità che vuoi eliminare.
Nota:assicurati che i feed di dati giornalieri contengano anche eventuali modifiche inviate tramite l'API di aggiornamento in tempo reale. In caso contrario, l'importazione collettiva 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 potrebbero verificarsi incoerenze nei dati. Utilizza invece i feed batch.
Convalida e codici di risposta dell'API
Esistono due tipi di convalide eseguite sulle chiamate API di aggiornamento in tempo reale:
- A livello di richiesta: queste convalide verificano che il payload rispetti 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 le entità nella richiesta sono state messe 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 in 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 registrati solo nella dashboard Report RTU del Centro azioni.
Nota:un codice di risposta 200 non indica che tutte le entità sono state importate correttamente.
Quote API
Gli aggiornamenti dell'API in tempo reale hanno una quota di 1500 richieste ogni 60 secondi, ovvero in media 25 richieste al secondo. 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 a effettuare la chiamata a intervalli esponenzialmente maggiori finché non va a buon fine. Se esausti 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.