Le RTU sono destinate principalmente ad 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 del feed batch. Gli aggiornamenti in tempo reale vengono elaborati in non più di cinque minuti.
Configurazione di Google Cloud
- Configurare un progetto Google Cloud. Per accedere all'API RTU è necessario un progetto Google Cloud.
- Concedi l'accesso in modifica all'indirizzo food-support@google.com
- Comunica al tuo POC Google il numero di progetto della piattaforma Google Cloud.Il progetto della piattaforma Google Cloud deve essere associato al tuo account Centro azioni affinché gli aggiornamenti in tempo reale funzionino.
- Abilita l'API Maps Booking:
- In Google Cloud, vai ad API e servizi > Libreria.
- Cerca "API Google Maps Booking".
- Individua l'istanza di Sandbox ("API Google Maps Booking (Dev)") e fai clic su Abilita.
- Trova l'istanza Production ("API Google Maps Booking") e fai clic su Abilita
- Crea un account di servizio con ruolo editor per il tuo progetto Google Cloud. Per maggiori dettagli, vedi Configurazione dell'account di servizio.
- Assicurati di caricare 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 lo scambio di token manualmente, come descritto in Utilizzo di OAuth 2.0 per accedere alle API di Google.
Creazione dell'account di servizio
Per effettuare richieste HTTPS autenticate alle API di Google, ad esempio l'API degli aggiornamenti in tempo reale, devi avere un account di servizio.
Per configurare un account di servizio, segui questi passaggi:
- 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 per concedere loro l'accesso all'account di servizio e fai clic su Fine.
- Fai clic su Altro > Crea chiave per l'account di servizio 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 Real-time 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 se includi più aggiornamenti in una singola richiesta API. Puoi raggruppare fino a 1000 aggiornamenti in una singola chiamata API. Consigliamo di utilizzare un approccio basato su trigger per inviare gli aggiornamenti tramite RTU (ovvero quando una modifica dei dati nel sistema attiva un aggiornamento in tempo reale a Google) anziché un approccio basato sulla frequenza (ovvero ogni X minuti esegue una scansione del sistema per rilevare eventuali modifiche).
L'API di aggiornamenti in tempo reale funziona sia in ambiente sandbox che in ambiente di produzione. L'ambiente sandbox viene utilizzato per testare le richieste API e l'ambiente di produzione per aggiornare i contenuti visibili agli utenti end-to-end che effettuano ordini.
- Sandbox -
partnerdev-mapsbooking.googleapis.com - Produzione -
mapsbooking.googleapis.com
Endpoint
L'API Real-Time Updates espone due endpoint per gestire le richieste in arrivo 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 nel Centro azioni nella pagina Account e utenti, come mostrato nel seguente screenshot.
Prendendo 10000001 come valore di PARTNER_ID come esempio dello screenshot sopra, gli URL completi per l'invio delle richieste API nella sandbox e in produzione saranno simili agli esempi riportati di seguito.
Aggiornamento della sandbox
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
ELIMINAZIONE sandbox
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 produzione
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
Aggiornare le 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 e un payload JSON contenente l'entità che vuoi aggiornare.
Nota: assicurati che i tuoi feed di dati giornalieri contengano anche le modifiche inviate tramite l'API di aggiornamento in tempo reale. In caso contrario, i tuoi dati potrebbero essere obsoleti o inattivi.
Payload richiesta di aggiornamento
Il corpo della richiesta è un oggetto JSON con un elenco di record. Ogni record corrisponde a un'entità che viene aggiornata. È composto dai campi proto_record e generation_timestamp che indicano l'ora dell'aggiornamento dell'entità:
{
"records": [
{
"proto_record":"ServiceData PROTO",
"generation_timestamp":"UPDATE_TIMESTAMP"
}
]
}
ServiceData PROTO: il protocollo o la traduzione JSON dell'entità ServiceData che stai aggiornando.UPDATE_TIMESTAMP: assicurati di includere il timestamp relativo alla generazione dell'entità nei sistemi di backend. Se questo campo non viene 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 delle entità. Controlla il formato previsto dei valori temporali nello schema dell'inventario relazionale.
- Il corpo del payload non deve superare i 5 MB.
- Elimina gli spazi vuoti per ridurre le dimensioni.
- In una richiesta
batchPushpossono esserci fino a 1000 aggiornamenti.
Esempi
Aggiorna un orario di arrivo stimato
Supponiamo che tu debba aggiornare con urgenza l'orario di arrivo stimato di un servizio di consegna da 30-60 a 60-90 minuti. L'aggiornamento deve contenere il codice JSON per l'intera entità Service.
Considera un'entità di servizio che abbia 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"
}
}
I tuoi aggiornamenti in tempo reale tramite HTTP POST sono i seguenti (il corpo della richiesta è stampato per favorire la leggibilità):
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"
}]
}
Aggiorna 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"
}]
}
Elimina entità
Per eliminare 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à da eliminare.
Nota: assicurati che i tuoi 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"
}]
}
Aggiungere entità
Non utilizzare gli aggiornamenti in tempo reale per aggiungere nuove entità, poiché ciò potrebbe causare incoerenze nei dati. Utilizza invece feed in gruppo.
Convalida e codici di risposta dell'API
Per le chiamate API di aggiornamento in tempo reale vengono eseguiti due tipi di convalide:
- A livello di richiesta: queste convalide controllano 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 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 inproto_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 riportate solo nella dashboard Report RTU del Centro azioni.
Nota:un codice di risposta 200 non significa che tutte le entità sono state importate correttamente.
Quote API
Gli aggiornamenti API in tempo reale hanno una quota di 1500 richieste ogni 60 secondi o 25 richieste al secondo in media. Quando viene superata una quota, Google risponde con il seguente messaggio di errore:
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}
Per gestirla, ritenta la chiamata a intervalli esponenzialmente più grandi finché l'operazione non va a buon fine. Se esaurisci regolarmente la quota, valuta la possibilità di includere più entità in un'unica richiesta API. Puoi includere fino a 1000 entità in una sola chiamata API.
Tempi di elaborazione: aggiornamenti in tempo reale
Un'entità aggiornata tramite un aggiornamento in tempo reale viene elaborata entro 5 minuti.