Questa pagina è stata tradotta dall'API Cloud Translation.

Aggiornamento in tempo reale

Aggiornamenti in tempo reale

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.
- Concedi l'accesso come editor a food-support@google.com
- 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.
    .
  - Crea un account di servizio con un ruolo di editor per il progetto Google Cloud. Per maggiori dettagli, vedi Configurazione dell'account di servizio.
  - 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:

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

Aggiornamento della sandbox

https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush

ELIMINA 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

ELIMINA Produzione

https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete

Aggiornamento delle entità

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à:

  {
    "records": [
      {
        "proto_record":"ServiceData PROTO",
        "generation_timestamp":"UPDATE_TIMESTAMP"
      }
    ]
  }

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:

{
	"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"
	}
}

L'aggiornamento in tempo reale tramite HTTP POST è il seguente (il corpo delle richieste è stampato per una maggiore 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"
  }]
}

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

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"
  }]
}

Aggiunta di entità

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:

{
  "error": {
    "code": 429,
    "message": "Insufficient tokens for quota ...",
    "status": "RESOURCE_EXHAUSTED",
    "details": [...]
  }
}

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.

Indietro

Monitoraggio delle conversioni