Aggiornamenti in tempo reale dell'API

L'inventario nel tuo sistema varia nell'arco della giornata a causa di nuove prenotazioni, annullamenti e modifiche alla pianificazione da parte dei commercianti. L'API di aggiornamento in tempo reale è un meccanismo per notificare a Google questi cambiamenti nella disponibilità dell'inventario. Puoi anche utilizzare gli aggiornamenti API in tempo reale per notificare a Google le modifiche apportate alle prenotazioni esistenti.

Gli aggiornamenti in tempo reale non sono necessari se tutti i tuoi commercianti utilizzano la funzionalità della lista d'attesa.

Feed e aggiornamenti in tempo reale delle API

Gli aggiornamenti in tempo reale delle API vengono utilizzati per notificare a Google modifiche incrementali relative alla disponibilità dell'inventario e alle prenotazioni in tempo reale. Oltre agli aggiornamenti in tempo reale dell'API, invia ogni giorno feed di disponibilità completi per assicurarti che Google disponga della conoscenza più accurata e aggiornata della disponibilità nel tuo sistema. I feed completi fungono da istantanea dello stato attuale della disponibilità dell'inventario nel tuo sistema.

Sebbene gli aggiornamenti delle API possano essere utilizzati per aggiornare qualsiasi informazione fornita dai feed, ad esempio informazioni su commercianti e servizi, in genere vengono utilizzati solo per aggiornare le informazioni sulla disponibilità.

API di aggiornamento in tempo reale obbligatorie

API di aggiornamento in tempo reale (RTU)
BookingNotification	Obbligatorio	Invia le RTU di BookingNotification ogni volta che si verifica una modifica alla prenotazione (ad es. modifiche o cancellazioni).
Disponibilità Sostituisce RTU	Condizionatamente richiesto[1]	Invia RTU di sostituzione in gruppo o sostituzione singola per inviare aggiornamenti sulla disponibilità dell'inventario. La propagazione e l'applicazione delle modifiche potrebbero richiedere diversi minuti.
RTU commerciante	Facoltativo	Invia le RTU del commerciante se vuoi apportare modifiche alle informazioni sul commerciante in tempo reale. La propagazione e l'applicazione delle modifiche possono richiedere diverse ore.
RTU servizio	Facoltativo	Invia le RTU dei servizi se vuoi apportare modifiche alle informazioni sui servizi in tempo reale. Un caso d'uso comune è che se i prezzi dei servizi variano drasticamente durante il giorno, si consiglia l'implementazione delle RTU del servizio per evitare errori degli ordini dovuti a mancate corrispondenze di prezzo. La propagazione e l'applicazione delle modifiche potrebbero richiedere diverse ore.

Nota: il requisito per questo endpoint cambia in base alla tua integrazione. Rivolgiti al tuo contatto Google per determinare quali endpoint sono richiesti.

Disponibilità Sostituire RTU API

Utilizza l'API sostitutiva disponibilità per fornire aggiornamenti sulla disponibilità nei seguenti casi d'uso:

• Un utente prenota una prenotazione sul tuo sistema, quindi lo slot di disponibilità non è più disponibile.
• Un commerciante modifica la sua disponibilità nel tuo sistema.
• Un utente prenota tramite Google, quindi lo slot di disponibilità non è più disponibile.
• Una prenotazione effettuata tramite Google viene annullata sul tuo account, ad esempio direttamente dal commerciante. Devi aggiornare la prenotazione e la disponibilità, perché lo slot originale è ora di nuovo disponibile.
• Una chiamata BatchAvailabilityLookup del server di prenotazione restituisce l'inventario che non corrisponde a quello effettivo.

Per saperne di più, consulta le seguenti risorse:

• Tutorial: come strutturare gli aggiornamenti in tempo reale
• Esempio di client Java per gli aggiornamenti in tempo reale mediante chiamate RESTful
• Pagina di riferimento API di aggiornamento dell'inventario

RTU API Booking Notification

L'API Booking Notification avvisa Google degli aggiornamenti alle prenotazioni esistenti. Quando invii un aggiornamento sugli annullamenti, invia solo le informazioni essenziali nella richiesta con il parametro di query updateMask. Ecco un esempio:

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"CANCELED"}

Accesso all'API

Creare un account di servizio

Utilizza la scheda Credenziali nella console API di Google per creare un account di servizio. Archivia la chiave privata in formato JSON in un luogo sicuro. Quando crei l'account, hai la possibilità di impostare il ruolo su "Proprietario".

Autentica le API Maps Booking

Dopo aver creato un account di servizio, autentica le seguenti API:

• API Google Maps Booking
• API Google Maps Booking (Dev)

Per una guida passo passo su come eseguire questa operazione, consulta il tutorial Autenticazione con l'API Maps Booking.

Utilizza le chiamate RESTful o scarica la libreria client

Ti consigliamo di effettuare chiamate RESTful direttamente all'API Maps Booking con payload JSON. Per maggiori informazioni, consulta la documentazione relativa all'API REST.

Puoi anche utilizzare librerie client per connetterti all'API.

linguaggio	Link di download
Java	Libreria client Java. Per maggiori informazioni, consulta le istruzioni per il client Java.

Sono disponibili per il download ulteriori librerie di supporto che gestiscono l'autorizzazione e altri aspetti delle chiamate alle API di Google. Se necessario, dai un'occhiata a questi esempi.

Recupera il documento di rilevamento

Per alcune librerie client, come Ruby, è necessario recuperare il documento di rilevamento per l'API, che descrive metodi e parametri.

Utilizza questo comando per recuperare il documento di rilevamento:

curl -s -o 'mapsbooking_rest' 'https://mapsbooking.googleapis.com/$discovery/rest?version=v1alpha'

Per maggiori informazioni sull'accesso all'API da Ruby, segui questi link: Client API Ruby e libreria di autenticazione Ruby.

Effettuare chiamate autorizzate all'API

Quando effettui chiamate all'API, consulta Preparazione per una chiamata API autorizzata per autorizzare il tuo account di servizio con la tua chiave privata e il seguente ambito OAuth: https://www.googleapis.com/auth/mapsbooking.

Quote API

Gli aggiornamenti delle API hanno una quota di 1500 richieste ogni 60 secondi o 25 richieste al secondo in media. Quando viene superata una quota (il che può verificarsi se non hai aggiunto il numero di progetto Google Cloud corretto nel Portale partner), 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 eseguire la chiamata a intervalli esponenzialmente più grandi fino a quando la chiamata non va a buon fine. Se esaurisci regolarmente la quota con ReplaceServiceAvailability, passa a BatchReplaceServiceAvailabily per ridurre il numero di chiamate API. Questo metodo consente di aggiornare più servizi in una singola chiamata API.

Sandbox e endpoint di produzione

Tramite l'API puoi effettuare chiamate sia all'ambiente sandbox sia all'ambiente di produzione. Assicurati di aver abilitato entrambe le API nel tuo progetto Google Cloud. Entrambe queste API utilizzano lo stesso ambito, ma hanno endpoint diversi.

Endpoint di produzione: https://mapsbooking.googleapis.com/

Endpoint sandbox: https://partnerdev-mapsbooking.googleapis.com/

Di seguito è riportato un esempio in Java di come cambiare endpoint:

    // This block of code is for OAuth and is the same for prod and sandbox.
    GoogleCredential
      .fromStream(new FileInputStream(...))
      .createScoped(Collections.singleton("https://www.googleapis.com/auth/mapsbooking"))

    // This block of code sets the endpoint. This is what you'd change to connect to the sandbox.
    new GoogleMapsBookingAPI.Builder(...)
      .setApplicationName(...)
      .setRootUrl("https://partnerdev-mapsbooking.googleapis.com/") // you add this to change the endpoint to use partnerdev.
      .build()