Le RTU sono principalmente destinate 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 in 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.
Comunica al tuo POC Google il numero del progetto Google Cloud.Affinché gli aggiornamenti in tempo reale funzionino, il tuo progetto Google Cloud deve essere associato al tuo account Actions Center.
Attiva API Maps Booking:
In Google Cloud, vai ad API e Servizi > Raccolta.
Cerca "API Google Maps Booking".
Trova l'istanza Sandbox ("API Google Maps Booking (Dev)") e fai clic su Abilita.
Individua l'istanza di produzione ("API Google Maps Booking") e fai clic su Abilita.
.
Assicurati di caricare i feed batch nell'ambiente in cui stai lavorando sugli 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 lo scambio di token, come descritto in Utilizzo di 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 aggiornamento 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 utenti per concedere loro l'accesso all'account di servizio e fai clic su Fine.
Fai clic su Altro> Crea la 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: Update ed Delete. 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 aggiornamenti tramite RTU (ovvero in seguito a una modifica dei dati nel sistema che attiva un aggiornamento in tempo reale a Google) anziché con un approccio basato sulla frequenza (ad esempio, se possibile, ogni X minuti scansiona il sistema per rilevare eventuali modifiche).
L'API di aggiornamento in tempo reale funziona sia in ambiente sandbox che in quello 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 degli aggiornamenti in tempo reale espone due endpoint per gestire le richieste in arrivo per gli aggiornamenti dell'inventario:
Il parametro PARTNER_ID è disponibile nel Centro azioni 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 nella sandbox e in produzione saranno mostrati negli esempi di seguito.
Per aggiornare le entità nell'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 feed di dati giornalieri contengano anche eventuali modifiche inviate tramite l'API Real-Time Updates. In caso contrario, i dati potrebbero non essere aggiornati o non aggiornati.
Aggiorna payload 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 generation_timestamp che indica l'ora dell'aggiornamento dell'entità:
ServiceData PROTO: la traduzione proto o 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 richiesta batchPush, il campo generation_timestamp viene utilizzato per il controllo delle versioni delle entità. Verifica il formato previsto dei valori temporali nello schema dell'inventario relazionale.
Il corpo del payload non deve avere dimensioni superiori a 5 MB.
Elimina gli spazi vuoti per ridurne le dimensioni.
Una richiesta batchPush può contenere fino a 1000 aggiornamenti.
Esempi
Aggiornare un orario di arrivo stimato
Supponiamo che tu debba urgentemente aggiornare 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.
Prendi in considerazione un'entità di servizio come la seguente:
Per eliminare entità dall'inventario, utilizza l'endpoint DELETE in una richiesta POST HTTP. Ogni richiesta POST deve includere il parametro PARTNER_ID e il payload JSON che contiene 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 batch giornaliera sovrascriverà le modifiche in tempo reale.
Non utilizzare gli aggiornamenti in tempo reale per aggiungere nuove entità, poiché ciò potrebbe causare incoerenze nei dati. Utilizza invece i feed in batch.
Convalida e Codici di risposta delle 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 segua lo schema e che ogni proto_record contenga i campi id e type. 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à in quella richiesta sono state messe in coda per l'elaborazione. Un codice di risposta non 200 indica che una o più di queste convalide non sono riuscite e l'intera richiesta è stata rifiutata (incluse tutte le entità nel payload). Ad esempio, se in proto_record manca 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 segnalate solo nella dashboard dei 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 delle API in tempo reale hanno una quota di 1500 richieste ogni 60 secondi, ovvero 25 richieste al secondo in media. Quando viene superata una quota, Google risponde con il seguente messaggio di errore:
Per gestire questo problema, riprova a effettuare la chiamata a intervalli esponenziali più grandi finché non viene eseguita correttamente. 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 chiamata API.
Aggiornamenti in tempo reale dei tempi di elaborazione
Un'entità aggiornata tramite un aggiornamento in tempo reale viene elaborata entro 5 minuti.