Aggiornamenti in tempo reale dell'API

L'inventario del tuo sistema varia nel corso della giornata a causa di nuove prenotazioni, annullamenti e pianificazioni di modifiche da parte dei commercianti. L'API di aggiornamento in tempo reale è un meccanismo per informare Google di queste modifiche nella disponibilità dell'inventario. Puoi anche utilizzare gli aggiornamenti in tempo reale dell'API per informare Google delle modifiche apportate alle prenotazioni esistenti.

Aggiornamenti e feed in tempo reale dell'API

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

Benché gli aggiornamenti delle API possano essere utilizzati per aggiornare qualsiasi informazione fornita dai feed, ad esempio le 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)
Notifica di prenotazione	Obbligatorio	Invia le RTU delle prenotazioni ogni volta che viene apportata una modifica alla prenotazione (ad es. modifiche o cancellazioni).
Disponibilità Sostituisci RTU	Condizione obbligatoria[1]	Invia RTU batch in sostituzione o sostituzione singola per inviare aggiornamenti alla disponibilità dell'inventario. La propagazione e l'applicazione delle modifiche potrebbero richiedere alcuni minuti.
RTU commerciante	Facoltativo	Invia le RTU del commerciante se vuoi apportare modifiche alle informazioni del commerciante in tempo reale. La propagazione e l'applicazione delle modifiche potrebbero richiedere diverse ore.
RTU di servizio	Facoltativo	Invia le RTU del servizio se vuoi modificare le informazioni sul servizio in tempo reale. Un caso d'uso comune è se i prezzi dei servizi variano drasticamente durante il giorno, consigliamo di implementare le RTU di servizio per evitare errori nell'ordine a causa di una mancata corrispondenza dei prezzi. La propagazione e la propagazione 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à Sostituisci API RTU

Utilizza l'APIinclusiva disponibilità per fornire aggiornamenti di disponibilità nei seguenti casi d'uso:

• Un utente prenota un soggiorno nel tuo sistema, quindi lo slot di disponibilità non è più disponibile.
• Un commerciante modifica la propria disponibilità nel tuo sistema.
• Un utente prenota tramite Google per una prenotazione, pertanto l'area disponibilità non è più disponibile.
• Una prenotazione effettuata tramite Google viene annullata, ad esempio, dal commerciante. Devi aggiornare la prenotazione e la disponibilità perché lo spazio originale ora è di nuovo disponibile.
• Una chiamata al server di prenotazione BatchAvailabilityLookup restituisce un inventario che non corrisponde all'inventario 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 tramite chiamate RESTful
• Pagina di riferimento dell'API per l'aggiornamento dell'inventario

Prenotazione dell'API delle notifiche di prenotazione

Le API delle notifiche di prenotazione comunicano a Google gli aggiornamenti alle prenotazioni esistenti. Quando invii un aggiornamento relativo agli annullamenti, invia solo le informazioni essenziali nella richiesta con il parametro di ricerca updateMask. Ad 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

Crea 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".

Autenticare le API di prenotazione di Maps

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 farlo, 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 ulteriori informazioni, consulta la documentazione relativa all'API REST.

Puoi anche utilizzare le librerie client per connetterti all'API.

Lingua	Link di download
Java	Libreria client Java. Per ulteriori informazioni, consulta le istruzioni per i client Java.

Sono disponibili librerie di assistenza aggiuntive per il download, 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, ad esempio Ruby, è necessario recuperare il documento di rilevamento per l'API, che descrive i relativi metodi e parametri.

Utilizza il seguente comando per recuperare il documento di rilevamento:

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

Per saperne di più sull'accesso all'API da Ruby, segui questi link: Ruby API Client e Ruby Auth Library.

Effettuare chiamate autorizzate all'API

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

Quote API

Gli aggiornamenti API hanno una quota di 1500 richieste ogni 60 secondi o 25 richieste al secondo in media. Quando viene superata una quota (che può verificarsi quando 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 questa situazione, riprova a chiamare a intervalli esponenzialmente più grandi finché l'operazione non andrà a buon fine. Se esaurisci regolarmente la quota con ReplaceServiceAvailability, passa a BatchReplaceServiceAvailabily per ridurre il numero di chiamate API. Questo metodo ti permette di aggiornare più servizi in una singola chiamata API.

Sandbox e endpoint di produzione

Puoi effettuare chiamate sia all'ambiente sandbox che a quello di produzione tramite l'API. Assicurati di aver attivato entrambe le API nel 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 su 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()