Passaggio 5: implementa gli aggiornamenti in tempo reale dell'API

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

Aggiornamenti e feed in tempo reale dell'API

Gli aggiornamenti in tempo reale dell'API vengono utilizzati per notificare a Google le modifiche incrementali alla disponibilità dell'inventario e alle prenotazioni man mano che si verificano in tempo reale. Oltre agli aggiornamenti in tempo reale dell'API, invia quotidianamente feed di disponibilità completi per assicurarti che Google disponga delle informazioni più accurate e aggiornate sulla disponibilità esistente nel tuo sistema. I feed completi fungono da istantanea dello stato corrente della disponibilità dell'inventario nel tuo sistema.

Sebbene gli aggiornamenti dell'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 richieste

Disponibilità sostituisci API RTU

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

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

API Booking Notification RTU

Le API di notifica delle prenotazioni informano Google degli aggiornamenti delle prenotazioni esistenti. Quando invii un aggiornamento sulle cancellazioni, 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

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

Autentica le API Maps Booking

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

• API Google Maps Booking
• API Google Maps Booking (per sviluppatori)

Per una guida passo passo su come eseguire questa operazione, consulta il tutorial sull'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 dell'API REST.

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

Sono disponibili per il download altre 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 scoperta dell'API, che descrive i relativi metodi e parametri.

Utilizza il seguente comando per recuperare il documento di Discovery:

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

Per ulteriori informazioni su come accedere all'API da Ruby, segui questi link: Ruby API Client e Ruby Auth Library.

Effettuare chiamate autorizzate all'API

Quando effettui chiamate all'API, consulta Preparazione per effettuare 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 dell'API hanno una quota di 1500 richieste ogni 60 secondi, ovvero in media 25 richieste al secondo. Quando una quota viene superata (il che può accadere se non hai aggiunto il numero del progetto Google Cloud corretto nel Partner Portal), 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 più lunghi finché non va a buon fine. Se esaurisci regolarmente la quota con ReplaceServiceAvailability, passa a BatchReplaceServiceAvailabily per ridurre il numero di chiamate API. Questo metodo ti consente di aggiornare più servizi in una singola chiamata API.

Endpoint di sandbox e produzione

Puoi effettuare chiamate sia all'ambiente sandbox sia all'ambiente di produzione tramite l'API. Assicurati di aver attivato 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()