Questa sezione descrive come inviare aggiornamenti dei feed a Google. L'API Incremental Updates consente di aggiornare ed eliminare le entità nei feed quasi in tempo reale.
Questa funzionalità è destinata principalmente ad aggiornamenti che non puoi prevedere, come le chiusure di emergenza. Di norma, qualsiasi modifica inviata tramite l'API Incremental Updates deve essere una modifica che deve essere pubblicata in non più di una settimana. Se la modifica non deve essere applicata immediatamente, puoi utilizzare un aggiornamento batch. Gli aggiornamenti incrementali vengono elaborati in non più di cinque minuti.
Configurazione
Per implementare aggiornamenti incrementali:
- Per creare un progetto, segui i passaggi descritti in Creare e configurare un progetto.
- Segui i passaggi descritti in Configurare un account di servizio per creare un account di servizio. Devi essere un "Proprietario" del progetto per aggiungere un ruolo "Editor" per l'account di servizio
- (Facoltativo, ma consigliato) Installa la libreria client di Google nella lingua che preferisci per agevolare l'utilizzo di OAuth 2.0 durante la chiamata all'API. Gli esempi di codice inclusi di seguito utilizzano queste librerie. In caso contrario, dovrai gestire manualmente gli scambi di token, come descritto in Utilizzare OAuth 2.0 per accedere alle API di Google.
Endpoint
Per informare Google di un aggiornamento, effettua una richiesta HTTP POST all'API IncrementalUpdates e includi un payload di aggiornamenti e aggiunte. Lo schema dell'inventario che utilizzi determina a quale endpoint effettuare la richiesta:
inventario v2
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID:push
inventario v1
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/ENTITY_ID:push
Per rimuovere un'entità, effettua una richiesta HTTP DELETE al seguente endpoint che corrisponde allo schema dell'inventario da utilizzare:
inventario v2
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
inventario v1
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
Nelle richieste riportate sopra, sostituisci quanto segue:
- PROJECT_ID: ID progetto Google Cloud associato al progetto che hai creato in Creare e configurare un progetto.
- TYPE (solo schema dell'inventario v2): il tipo di entità (proprietà
@type) dell'oggetto nel feed di dati da aggiornare. - ENTITY_ID: ID dell'entità inclusa nel payload. Assicurati di applicare la codifica URL al tuo ID entità.
- DELETE_TIME (solo eliminazione endpoint): campo facoltativo per indicare l'ora in cui l'entità è stata eliminata nei sistemi (il valore predefinito è il momento in cui viene ricevuta la richiesta). Il valore dell'ora non deve essere nel futuro. Quando invii un'entità
tramite una chiamata incrementale, il controllo delle versioni dell'entità
utilizza il campo
delete_timenel caso di una chiamata di eliminazione. Formatta questo valore comeyyyy-mm-ddTHH:mm:ssZ
Ad esempio, supponiamo che tu abbia un progetto con ID "delivery-provider-id" che utilizza lo schema dell'inventario v2. Vuoi apportare modifiche al ristorante con un tipo di entità ristorante "MenuSezione" e un ID entità "menuSezione_122". L'endpoint per gli aggiornamenti dei dati sarà il seguente:
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122:push
Per rimuovere la stessa entità, devi effettuare questa chiamata API HTTP DELETE:
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122?entity.vertical=FOODORDERING
Richieste sandbox
Per le richieste sandbox, segui le indicazioni riportate nella sezione Endpoint sopra, ma invia richieste a /v2/sandbox/apps/ anziché a /v2/apps/. Ad esempio, una richiesta di eliminazione sandbox per lo schema dell'inventario v2 è strutturata come segue:
https://actions.googleapis.com/v2/sandbox/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
Aggiornamenti e aggiunte
Anche i feed batch giornalieri devono contenere eventuali modifiche inviate tramite questa API. In caso contrario, gli aggiornamenti collettivi sovrascrivono le modifiche incrementali.
Payload
Ogni richiesta POST deve includere i parametri della richiesta insieme al payload JSON contenente i dati strutturati di qualsiasi tipo di entità elencato nello schema dell'inventario.
Il formato JSON dovrebbe avere lo stesso aspetto del feed batch, con le seguenti differenze:
- Il corpo del payload non deve superare i 5 MB. Come per i feed batch, ti consigliamo di eliminare gli spazi vuoti per poter inserire più dati.
- La busta è la seguente:
{
"entity": {
"data":"ENTITY_DATA",
"vertical":"FOODORDERING"
},
"update_time":"UPDATE_TIMESTAMP"
}
Nel payload riportato sopra, sostituisci quanto segue:
- ENTITY_DATA: entità in formato JSON serializzata come stringa. L'entità JSON-LD deve essere passata come stringa nel campo
data. - UPDATE_TIMESTAMP (facoltativo): timestamp relativo all'aggiornamento dell'entità nei sistemi. Il valore dell'ora non deve essere nel futuro. Il timestamp predefinito si riferisce al momento in cui Google riceve la richiesta. Quando invii un'entità tramite una richiesta incrementale, il controllo delle versioni dell'entità utilizza anche il campo
update_timenel caso di una richiesta di aggiunta/aggiornamento.
Aggiornamento di un'entità
Esempio 1: aggiornare un ristorante
Supponiamo che tu debba aggiornare con urgenza il numero di telefono di un ristorante. L'aggiornamento contiene il codice JSON per l'intero ristorante.
Prendi in considerazione un feed collettivo simile al seguente:
{
"@type": "Restaurant",
"@id": "restaurant12345",
"name": "Some Restaurant",
"url": "https://www.provider.com/somerestaurant",
"telephone": "+16501234567",
"streetAddress": "345 Spear St",
"addressLocality": "San Francisco",
"addressRegion": "CA",
"postalCode": "94105",
"addressCountry": "US",
"latitude": 37.472842,
"longitude": -122.217144
}
L'aggiornamento incrementale tramite HTTP POST sarebbe quindi il seguente:
POST v2/apps/provider-project/entities/Restaurant/restaurant12345:push
Host: actions.googleapis.com
Content-Type: application/ld+json
{
"entity": {
"data": {
"@type": "Restaurant",
"@id": "restaurant12345",
"name": "Some Restaurant",
"url": "https://www.provider.com/somerestaurant",
"telephone": "+16501235555",
"streetAddress": "345 Spear St",
"addressLocality": "San Francisco",
"addressRegion": "CA",
"postalCode": "94105",
"addressCountry": "US",
"latitude": 37.472842,
"longitude": -122.217144
},
"vertical": "FOODORDERING"
}
}
Esempio 2: aggiornare il prezzo di un elemento del menu
Supponiamo che tu debba modificare il prezzo di un elemento del menu. Come nell'esempio 1, l'aggiornamento deve contenere il codice JSON per l'intera entità di primo livello (il menu) e il feed utilizza lo schema di inventario v1.
Prendi in considerazione un feed collettivo simile al seguente:
{
"@type": "MenuItemOffer",
"@id": "menuitemoffer6680262",
"sku": "offer-cola",
"menuItemId": "menuitem896532",
"price": 3.00,
"priceCurrency": "USD"
}
L'aggiornamento incrementale tramite POST sarebbe il seguente:
POST v2/apps/provider-project/entities/MenuItemOffer/menuitemoffer6680262:push
Host: actions.googleapis.com
Content-Type: application/ld+json
{
"entity": {
"data": {
"@type": "MenuItemOffer",
"@id": "menuitemoffer6680262",
"sku": "offer-cola",
"menuItemId": "menuitem896532",
"price": 1.00,
"priceCurrency": "USD"
},
"vertical": "FOODORDERING"
}
}
Aggiunta di un'entità
Per aggiungere entità, evita di utilizzare gli aggiornamenti dell'inventario. Utilizza invece la procedura dei feed batch come descritto per lo schema dell'inventario v2.
Rimuovere un'entità
Per rimuovere le entità di primo livello, utilizza un endpoint leggermente modificato e nella richiesta utilizzi HTTP DELETE anziché HTTP POST.
Non utilizzare HTTP DELETE per rimuovere una sottoentità all'interno di un'entità di primo livello, come una voce di menu all'interno di un menu. Considera invece la rimozione delle entità secondarie come un aggiornamento di un'entità di primo livello in cui l'entità secondaria viene rimossa dall'elenco o dal parametro pertinente.
Esempio 1: eliminazione di un'entità di primo livello
Considera una situazione in cui vuoi eliminare un ristorante in un feed che utilizza lo schema di inventario v1. Devi anche eliminare i relativi servizi e menu.
Un endpoint di esempio per un'entità menu con ID "https://www.provider.com/ristorante/menu/nr":
DELETE v2/apps/delivery-provider-id/entities/https%3A%2F%2Fwww.provider.com%2Frestaurant%2Fmenu%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
Un endpoint di esempio per un'entità ristorante con ID "https://www.provider.com/ristorante/nr":
DELETE v2/apps/delivery-provider-id/entities/https%3A%2F%2Fwww.provider.com%2Frestaurant%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
Un endpoint di esempio per un'entità di servizio con ID "https://www.provider.com/ristorante/service/nr":
DELETE v2/apps/delivery-provider-id/entities/https%3A%2F%2Fwww.provider.com%2Frestaurant%2Fservice%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
}
Esempio 2: rimozione di entità secondarie
Per rimuovere un'entità secondaria da un'entità di primo livello, devi inviare l'entità di primo livello con l'entità secondaria rimossa dal campo corrispondente. L'esempio seguente presuppone che il feed utilizzi lo schema di inventario v1.
Ad esempio, per rimuovere un'area coperta dal servizio, aggiorna il servizio rimuovendo l'area coperta dal servizio dall'elenco areaServed.
POST v2/apps/delivery-provider-id/entities/https%3A%2F%2Fwww.provider.com%2Frestaurant%2Fservice%2Fnr:push
Host: actions.googleapis.com
Content-Type: application/ld+json
{
"entity": {
// Note: "data" is not serialized as a string in our example for readability.
"data": {
"@type": "Service",
"provider": {
"@type": "Restaurant",
"@id": "https://www.provider.com/restaurant/nr"
},
"areaServed": [
{
"@type": "GeoCircle",
"geoMidpoint": {
"@type": "GeoCoordinates",
"latitude": "42.362757",
"longitude": "-71.087109"
},
"geoRadius": "10000"
}
// area2 is removed.
]
...
},
"vertical": "FOODORDERING"
}
}
Codici di risposta API
Una chiamata riuscita non significa che il feed sia valido o corretto, ma solo che è stata effettuata la chiamata API. Le chiamate riuscite ricevono un codice di risposta HTTP 200, insieme a un corpo della risposta vuoto:
{}
In caso di errori, il codice di risposta HTTP non sarà 200 e il corpo della risposta indica l'errore.
Ad esempio, se l'utente ha impostato il valore "verticale" nella busta su FAKE_VERTICAL, verrà visualizzato il messaggio seguente:
{
"error": {
"code": 400,
"message": "Invalid value at 'entity.vertical' (TYPE_ENUM), \"FAKE_VERTICAL\"",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "entity.vertical",
"description": "Invalid value at 'entity.vertical' (TYPE_ENUM), \"FAKE_VERTICAL\""
}
]
}
]
}
}
Esempio di codice
Di seguito sono riportati alcuni esempi di come utilizzare l'API Incremental Updates in varie lingue. Questi esempi utilizzano le librerie di autenticazione di Google e presuppongono un feed che utilizza lo schema dell'inventario v1. Per soluzioni alternative, consulta l'articolo sull'utilizzo di OAuth 2.0 per applicazioni da server a server.
Aggiornare le entità
Node.js
Questo codice utilizza la libreria di autenticazione di Google per Node.js.
const {auth} = require('google-auth-library')
const request = require('request');
// The service account client secret file downloaded from the Google Cloud Console
const serviceAccountJson = require('./service-account.json')
// entity.json is a file that contains the entity data in json format
const entity = require('./entity.json')
const ENTITY_ID = 'restaurant/http://www.provider.com/somerestaurant'
const PROJECT_ID = 'your-project-id'
/**
* Get the authorization token using a service account.
*/
async function getAuthToken() {
let client = auth.fromJSON(serviceAccountJson)
client.scopes = ['https://www.googleapis.com/auth/assistant']
const tokens = await client.authorize()
return tokens.access_token;
}
/**
* Send an incremental update to update or add an entity
*/
async function updateEntity(entityId, entity) {
const token = await getAuthToken()
request.post({
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
},
url: `https://actions.googleapis.com/v2/apps/${PROJECT_ID}/entities/${encodeURIComponent(entityId)}:push`,
body: {
entity: {
data: JSON.stringify(entity),
vertical: 'FOODORDERING',
}
},
json: true
},
(err, res, body) => {
if (err) { return console.log(err); }
console.log(`Response: ${JSON.stringify(res)}`)
})
}
updateEntity(ENTITY_ID, entity)
Python
Questo codice utilizza la libreria di autenticazione di Google per Python.
from google.oauth2 import service_account
from google.auth.transport.requests import AuthorizedSession
import json
import urllib
PROJECT_ID = 'your-project-id'
ENTITY_ID = 'restaurant/http://www.provider.com/somerestaurant'
ENDPOINT = 'https://actions.googleapis.com/v2/apps/%s/entities/%s:push' % (
PROJECT_ID, urllib.quote(ENTITY_ID, ''))
# service-account.json is the service account client secret file downloaded from the
# Google Cloud Console
credentials = service_account.Credentials.from_service_account_file(
'service-account.json')
scoped_credentials = credentials.with_scopes(
['https://www.googleapis.com/auth/assistant'])
authed_session = AuthorizedSession(scoped_credentials)
# Retrieving the entity
update_file = open("entity.json") #JSON file containing entity data in json format.
data = update_file.read()
# Populating the entity with wrapper
entity = {}
entity['data'] = data #entity JSON-LD serialized as string
entity['vertical'] = 'FOODORDERING'
request = {}
request['entity'] = entity
response = authed_session.post(ENDPOINT, json=request)
print(response.text) #if successful, will be '{}'
Java
Questo codice utilizza la libreria di autenticazione di Google per Java.
private static final String PROJECT_ID = "your-project-id";
private static final String ENTITY_ID = "http://www.provider.com/somerestaurant";
/**
* Get the authorization token using a service account.
*/
private static String getAuthToken() {
InputStream serviceAccountFile =
Example.class.getClassLoader().getResourceAsStream("service-account.json");
ServiceAccountCredentials.Builder credentialsSimpleBuilder =
ServiceAccountCredentials.fromStream(serviceAccountFile).toBuilder();
credentialsSimpleBuilder.setScopes(ImmutableList.of("https://www.googleapis.com/auth/assistant"));
AccessToken accessToken = credentialsSimpleBuilder.build().refreshAccessToken();
return accessToken.getTokenValue();
}
/**
* Send an incremental update to update or add an entity.
* @param entityId The id of the entity to update.
* @param entity the json of the entity to be updated.
*/
public void updateEntity(String entityId, JSONObject entity) {
String authToken = getAuthToken();
String endpoint = String.format(
"https://actions.googleapis.com/v2/apps/%s/entities/%s:push",
PROJECT_ID, URLEncoder.encode(entityId, "UTF-8"));
JSONObject data = new JSONObject();
data.put("data", entity.toString());
data.put("vertical", "FOODORDERING");
JSONObject jsonBody = new JSONObject();
jsonBody.put("entity", data);
// Execute POST request
executePostRequest(endpoint, authToken, jsonBody);
}
Rimuovere entità
Node.js
Questo codice utilizza la libreria di autenticazione di Google per Node.js.
const {auth} = require('google-auth-library')
const request = require('request');
// The service account client secret file downloaded from the Google Cloud Console
const serviceAccountJson = require('./service-account.json')
// entity.json is a file that contains the entity data in json format
const entity = require('./entity.json')
const ENTITY_ID = 'restaurant/http://www.provider.com/somerestaurant'
const PROJECT_ID = 'your-project-id'
/**
* Get the authorization token using a service account.
*/
async function getAuthToken() {
let client = auth.fromJSON(serviceAccountJson)
client.scopes = ['https://www.googleapis.com/auth/assistant']
const tokens = await client.authorize()
return tokens.access_token;
}
/**
* Send an incremental update to delete an entity
*/
async function deleteEntity(entityId) {
const token = await getAuthToken()
request.delete({
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
},
url: `https://actions.googleapis.com/v2/apps/${PROJECT_ID}/entities/${encodeURIComponent(entityId)}?entity.vertical=FOODORDERING`,
body: {},
json: true
},
(err, res, body) => {
if (err) { return console.log(err); }
console.log(`Response: ${JSON.stringify(res)}`)
})
}
deleteEntity(ENTITY_ID)
Python
Questo codice utilizza la libreria di autenticazione di Google per Python.
from google.oauth2 import service_account
from google.auth.transport.requests import AuthorizedSession
import json
import urllib
# Service config
PROJECT_ID = 'your-project-id'
ENTITY_ID = 'restaurant/http://www.provider.com/somerestaurant'
DELETE_TIME = '2018-04-07T14:30:00-07:00'
ENDPOINT = 'https://actions.googleapis.com/v2/apps/%s/entities/%s?entity.vertical=FOODORDERING&delete_time=%s' % (
PROJECT_ID, urllib.quote(ENTITY_ID, ''), urllib.quote(DELETE_TIME, ''))
# service-account.json is the service account client secret file downloaded from the
# Google Cloud Console
credentials = service_account.Credentials.from_service_account_file(
'service-account.json')
scoped_credentials = credentials.with_scopes(
['https://www.googleapis.com/auth/assistant'])
authed_session = AuthorizedSession(scoped_credentials)
response = authed_session.delete(ENDPOINT)
print(response.text) #if successful, will be '{}'
Java
Questo codice utilizza la libreria di autenticazione di Google per Java.
private static final String PROJECT_ID = "your-project-id";
private static final String ENTITY_ID = "restaurant/http://www.provider.com/somerestaurant";
/**
* Get the authorization token using a service account.
*/
private static String getAuthToken() {
InputStream serviceAccountFile = Example.class.getClassLoader().getResourceAsStream("service-account.json");
ServiceAccountCredentials.Builder credentialsSimpleBuilder =
ServiceAccountCredentials.fromStream(serviceAccountFile).toBuilder();
credentialsSimpleBuilder.setScopes(ImmutableList.of("https://www.googleapis.com/auth/assistant"));
AccessToken accessToken = credentialsSimpleBuilder.build().refreshAccessToken();
return accessToken.getTokenValue();
}
/**
* Send an incremental update to delete an entity.
* @param entityId The id of the entity to delete.
*/
public void deleteEntity(String entityId) {
String authToken = getAuthToken();
String endpoint = String.format(
"https://actions.googleapis.com/v2/apps/%s/entities/%s?entity.vertical=FOODORDERING",
PROJECT_ID, URLEncoder.encode(entityId, "UTF-8"));
// Execute DELETE request
System.out.println(executeDeleteRequest(endpoint, authToken));
}
Casi d'uso
I seguenti casi d'uso sono esempi di aggiornamenti incrementali, aggiornamenti completi dei feed e contenuti ad alto livello nella chiamata API:
| Scenario | Entità di primo livello | Descrizione ed effetti |
|---|---|---|
| Disattivazione di un servizio | DisabledService |
Devi disattivare un servizio per un motivo imprevisto. Aggiornamenti incrementali: invia l'entità Feed completi: assicurati di aggiornare l'entità dai feed completi
in modo che il valore |
| Un articolo specifico non è disponibile | Menu |
Aggiornamenti incrementali: invia l'entità Menu
incapsulante con offer.inventoryLevel impostato su 0 per il valore
MenuItem specificato e tutti gli altri dati invariati. |
| Variazione di prezzo dell'elemento del menu | Menu |
Aggiornamenti incrementali: invia l'entità Menu
incapsulante con offer.price impostato sul prezzo aggiornato per il valore
MenuItem specificato e tutti gli altri dati invariati. |
|
Aggiungi nuova entità di primo livello Applicabile solo per le entità di tipo |
Menu, Restaurant e Service |
Ad esempio, devi aggiungere un nuovo menù a un ristorante. Aggiornamenti incrementali: invia la nuova entità del menu, insieme all'entità
del ristorante con il campo |
|
Elimina definitivamente l'entità di primo livello Applicabile solo per le entità di tipo |
Menu, Restaurant e Service |
Aggiornamenti incrementali: invia un'eliminazione esplicita. Feed completi: assicurati di rimuovere l'entità dai feed completi prima del successivo recupero da parte di Google, altrimenti l'entità verrà nuovamente aggiunta. |
Aggiungi una nuova area di consegna in una località Service specifica |
Service |
Feed incrementali: invia l'entità Service in questione con tutti i campi
invariati, come faresti normalmente nei feed completi, con la nuova area di consegna
specificata all'interno di areaServed di Service. |
Aggiorna l'orario di arrivo previsto per la consegna a Service |
Service |
Feed incrementali: invia lo Service come nei
feed, tranne per il fatto che hoursAvailable.deliveryHours viene aggiornato
di conseguenza. |
Aggiorna i prezzi di consegna in Service |
Service |
Feed incrementali: invia Service completi con
offers.priceSpecification.price aggiornato. |
Aggiorna gli orari di consegna o asporto in Service |
Service |
Feed incrementali: invia lo Service come nei
feed, tranne per il fatto che hoursAvailable viene aggiornato
di conseguenza. |
Service (modifica dell'importo minimo dell'ordine) |
Service |
Feed incrementali: invia Service completo con
Service.offers.priceSpecification.eligibleTransactionVolume
aggiornato |
Elimina MenuItem in modo permanente |
Menu |
Feed incrementali: invia lo Menu come nei
feed, ma rimuovendo questo MenuItem dall'elenco
hasMenuItems. |
SLO sul tempo di elaborazione per job batch e aggiornamenti incrementali
Un'entità aggiunta tramite un aggiornamento batch o incrementale verrà elaborata entro uno o due giorni. Un'entità aggiornata o eliminata tramite un batch viene elaborata entro due ore, mentre un'entità aggiornata tramite un aggiornamento incrementale viene elaborata entro cinque minuti. Un'entità inattiva viene eliminata dopo 7 giorni.
Puoi inviare a Google:
- Più job batch al giorno per mantenere aggiornato l'inventario OPPURE
- Un job batch al giorno e API incrementali per mantenere aggiornato l'inventario.