In diesem Abschnitt wird beschrieben, wie Sie zeitkritische Aktualisierungen Ihres Inventars senden können. Rechtspersönlichkeiten an Google senden. Mit der Inkrementelle Update API können Sie Updates per Push übertragen und in Ihrem Sandbox- oder Produktionsinventar nahezu in Echtzeit.
Diese Funktion ist hauptsächlich für Updates gedacht, die Sie nicht vorhersehen können, z. B. bei Notrufen. In der Regel gilt, dass jede Änderung, die über das Die Inkrement-Update-API sollte eine Änderung sein, die maximal eine Stunde. Muss Ihre Änderung nicht sofort übernommen werden, können Sie die Batchaufnahme. Inkrementelle Aktualisierungen werden in maximal fünf Minuten verarbeitet.
Vorbereitung
Die folgenden Punkte sind erforderlich, bevor Sie inkrementelle Updates implementieren:
- Es wird ein Dienstkonto mit der Rolle „Bearbeiter“ für Ihr Actions-Projekt erstellt. Weitere Informationen finden Sie unter Projekt erstellen und einrichten
- Produktions- oder Sandbox-Datenfeeds werden gehostet und aufgenommen. Weitere Informationen finden Sie unter Batch-Aufnahme.
- Optional, aber empfohlen: Google-Clientbibliothek installieren in der Sprache Ihrer Wahl, um die Verwendung von OAuth 2.0 beim Aufrufen der der API erstellen. Diese Bibliotheken werden in den unten aufgeführten Codebeispielen verwendet. Andernfalls müssen Tokenaustausch manuell durchführen, wie unter OAuth 2.0 für den Zugriff auf Google APIs verwenden beschrieben.
Endpunkte
Ersetzen Sie in den Anfragen unten Folgendes:
- PROJECT_ID: Google Cloud-Projekt-ID, die mit dem Projekt verknüpft ist, das Sie die unter Projekt erstellen und einrichten erstellt wurden.
- TYPE: Der Entitätstyp (Attribut
@type
) des Objekts in Ihrem Datenfeed, das Sie aktualisieren möchten. - ENTITY_ID (nur Endpunkt löschen): ID der zu löschenden Entität. Achten Sie darauf, Die Entitäts-ID muss URL-codiert werden.
- DELETE_TIME (nur Endpunkt löschen): Optionales Feld zur Kennzeichnung des
Zeitpunkt, zu dem die Entität in Ihren Systemen gelöscht wurde (standardmäßig die Anfrage
empfangen). Der Zeitwert darf nicht in der Zukunft liegen. Beim Senden einer Entität
durch einen inkrementellen Aufruf, Entitätsversionsverwaltung
verwendet im Falle eines Löschaufrufs auch das Feld
delete_time
. Formatieren Wert alsyyyy-mm-ddTHH:mm:ssZ
Endpunkt aktualisieren
Stellen Sie eine HTTP-POST-Anfrage an den folgenden Endpunkt, um eine Entität zu ändern sowie eine Nutzlast mit Updates und Ergänzungen. Sie können in einem einzigen API-Aufruf bis zu 1.000 Entitäten aktualisieren.
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities:batchPush
Wenn Sie beispielsweise Entitäten in einem Projekt mit der ID „delivery-provider-id“ aktualisieren möchten wäre der Endpunkt:
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities:batchpush
Endpunkt löschen
Senden Sie eine HTTP-DELETE-Anfrage an den folgenden Endpunkt, um eine Entität in Ihrem Inventar zu löschen.
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
Um beispielsweise einen „MenuSection“ Entität mit der ID „menuSection_122“ aus Ihrer „delivery-provider-id“ verwenden Sie einen HTTP DELETE API-Aufruf an:
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122?entity.vertical=FOODORDERING
Sandbox-Umgebung
Wenn Sie die API für inkrementelle Updates in Ihrem Sandbox-Inventar verwenden möchten, folgen Sie der Anleitung in den Endpunkten oben, aber
Anfragen an /v2/sandbox/apps/
statt an /v2/apps/
stellen
https://actions.googleapis.com/v2/sandbox/apps/PROJECT_ID/entities:batchPush
https://actions.googleapis.com/v2/sandbox/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
Entitäten aktualisieren
Jede POST-Anfrage muss die Anfrageparameter zusammen mit dem JSON-Code enthalten. Nutzlast, die die strukturierten Daten eines beliebigen Entitätstyps enthält, der in den Inventarschema.
Nutzlast aktualisieren
Die JSON-Datei sollte wie im Batch-Feed aussehen, mit den folgenden Zeichen: folgenden Unterschieden:
- Der Nutzlasttext darf nicht größer als 5 MB sein. Ähnlich wie im Batch -Feeds, empfehlen wir, Leerzeichen zu entfernen, damit mehr Daten unterzubringen sind.
- Der Umschlag lautet:
{ "requests": [ { "entity": { "data":"ENTITY_DATA", "name": "apps/project_id>/entities/type/entity_id" }, "update_time":"UPDATE_TIMESTAMP" }, ], "vertical": "FOODORDERING" }
Ersetzen Sie in der obigen Nutzlast Folgendes:
- ENTITY_DATA: Entität im JSON-Format serialisiert als String. Die
JSON-LD-Entität muss als String im Feld
data
übergeben werden. - UPDATE_TIMESTAMP (optional): Zeitstempel für die Aktualisierung der Entität in
Ihren Systemen. Der Zeitwert darf nicht in der Zukunft liegen. Der Standardzeitstempel ist der Zeitpunkt,
Google erhält die Anfrage. Wenn Sie eine Entität über eine
-Anfrage verwendet, verwendet die Entitätsversionsverwaltung auch die
update_time
im Fall einer Anfrage zum Hinzufügen/Aktualisieren.
Beispiele
Beispiel 1: Restaurant aktualisieren
Angenommen, Sie müssen die Telefonnummer eines Restaurants dringend aktualisieren. Ihr update enthält die JSON-Datei für das gesamte Restaurant.
Stellen Sie sich einen Batch-Feed vor, der so aussieht:
{ "@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 }
Dann würde Ihr inkrementelles Update per HTTP POST so aussehen:
POST v2/sandbox/apps/provider-project/entities:batchPush Host: actions.googleapis.com Content-Type: application/ld+json { "requests": [ { "entity": { "name": "apps/provider-project/entities/restaurant/restaurant12345", "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" }
Beispiel 2: Mehrere Restaurants aktualisieren
Um zwei Restaurantentitäten in einem einzigen API-Aufruf zu aktualisieren, sieht die HTTP-POST-Anfrage so aus:
POST v2/sandbox/apps/provider-project/entities:batchPush Host: actions.googleapis.com Content-Type: application/ld+json { "requests": [ { "entity": { "name": "apps/provider-project/entities/restaurant/restaurant12345", "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 } } }, { "entity": { "name": "apps/provider-project/entities/restaurant/restaurant123", "data": { "@type": "Restaurant", "@id": "restaurant123", "name": "Some Other Restaurant", "url": "https://www.provider.com/somerestaurant", "telephone": "+16501231235", "streetAddress": "385 Spear St", "addressLocality": "San Mateo", "addressRegion": "CA", "postalCode": "94115", "addressCountry": "US" } } } ] "vertical": "FOODORDERING" }
Beispiel 3: Preis für Artikel auf einer Speisekarte aktualisieren
Angenommen, Sie müssen den Preis eines Artikels auf der Speisekarte ändern. Wie in Beispiel 1 wird Ihr Update muss die JSON-Datei für die gesamte übergeordnete Entität (das Menü) enthalten und die -Feed verwendet das V1-Inventarschema.
Stellen Sie sich einen Batch-Feed vor, der so aussieht:
{ "@type": "MenuItemOffer", "@id": "menuitemoffer6680262", "sku": "offer-cola", "menuItemId": "menuitem896532", "price": 3.00, "priceCurrency": "USD" }
Dann würde Ihr inkrementelles Update per POST wie folgt aussehen:
POST v2/sandbox/apps/provider-project/entities:batchPush Host: actions.googleapis.com Content-Type: application/ld+json { "requests": [ { "entity": { "name": "apps/provider-project/entities/menuitemoffer/menuitemoffer6680262", "data": { "@type": "MenuItemOffer", "@id": "menuitemoffer6680262", "sku": "offer-cola", "menuItemId": "menuitem896532", "price": 1.00, "priceCurrency": "USD" }, "vertical": "FOODORDERING" } } ] "vertical": "FOODORDERING" }
Entität hinzufügen
Verwenden Sie keine Inventaraktualisierungen, um Entitäten hinzuzufügen. Verwenden Sie stattdessen Batch-Feeds wie für das v2-Inventarschema beschrieben.
Entität entfernen
Um Entitäten der obersten Ebene zu entfernen, verwenden Sie einen leicht modifizierten endpoint, und verwenden Sie in der Anfrage HTTP DELETE anstelle von HTTP POST.
Entität der obersten Ebene löschen
Stellen Sie sich vor, Sie möchten ein Restaurant aus einem Feed löschen. Du musst auch die zugehörigen Dienste und Speisekarten löschen.
Beispielendpunkt für eine Menüentität mit ID "provider/restaurant/menu/nr":
DELETE v2/apps/delivery-provider-id/entities/menu/provider%2Frestaurant%2Fmenu%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
Beispielendpunkt für eine Restaurantentität mit ID "https://www.provider.com/restaurant/nr":
DELETE v2/apps/delivery-provider-id/entities/restaurant/provider%2Frestaurant%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
Ein Beispielendpunkt für eine Dienstentität mit ID "https://www.provider.com/restaurant/service/nr":
DELETE v2/apps/delivery-provider-id/entities/service/provider%2Frestaurant%2Fservice%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
}
Unterentitäten entfernen
Verwenden Sie HTTP DELETE nicht, um eine Unterentität innerhalb einer übergeordneten Entität zu entfernen, z. B. ein Menüelement innerhalb eines Menüs. Behandeln Sie das Entfernen von Unterentitäten als Aktualisierung auf eine übergeordnete Entität, bei der die Unterentität aus der relevante Liste oder reverseReference enthält.
API-Antwortcodes
Ein erfolgreicher Aufruf bedeutet nicht, dass der Feed gültig oder korrekt ist, sondern nur, dass der API-Aufruf wurde ausgeführt. Erfolgreiche Aufrufe erhalten den HTTP-Antwortcode 200 sowie mit leerem Antworttext:
{}
Bei Fehlern ist der HTTP-Antwortcode nicht 200 und der Antworttext ist nicht zeigt an, was schiefgelaufen ist.
Wenn der Nutzer beispielsweise die Branche in den Umschlag ein,
FAKE_VERTICAL
, erhalten Sie die folgende Nachricht:
{
"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\""
}
]
}
]
}
}
Codebeispiel
Unten sehen Sie einige Beispiele für die Verwendung der API für inkrementelle Updates auf verschiedenen Sprachen. In diesen Beispielen werden die Google Auth Libraries verwendet. Es wird davon ausgegangen, dass ein Feed mit das Inventarschema von V1. Alternative Lösungen finden Sie unter OAuth 2.0 für Server-zu-Server-Anwendungen verwenden.
Entitäten aktualisieren
Node.js
In diesem Code wird die Google-Authentifizierungsbibliothek für Node.js verwendet.
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 = 'your/entity/id' const PROJECT_ID = 'type/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(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:batchPush`, body: { requests: [ { entity: { data: JSON.stringify(entity) name: `apps/${PROJECT_ID}/entities/${ENTITY_ID}` } } ], vertical: 'FOODORDERING' }, json: true }, (err, res, body) => { if (err) { return console.log(err); } console.log(`Response: ${JSON.stringify(res)}`) }) } updateEntity(entity)
Python
In diesem Code wird die Google-Authentifizierungsbibliothek für Python verwendet.
from google.oauth2 import service_account from google.auth.transport.requests import AuthorizedSession import json import urllib PROJECT_ID = 'your-project-id' ENTITY_ID = 'type/your/entity/id' ENDPOINT = 'https://actions.googleapis.com/v2/apps/%s/entities:batchPush' % ( PROJECT_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() entity = {} entity['data'] = data #entity JSON-LD serialized as string entity['name'] = 'apps/%s/entities/%s' % (PROJECT_ID, urllib.quote(ENTITY_ID, '') ) # Populating the request request = {} request['entity'] = entity requestArray = [request] # Populating the payload payload = {} payload['requests'] = requestArray payload['vertical'] = 'FOODORDERING' response = authed_session.post(ENDPOINT, json=payload) print(response.text) #if successful, will be '{}'
Java
In diesem Code wird die Google-Authentifizierungsbibliothek für Java verwendet.
private static final String PROJECT_ID = "your-project-id"; private static final String ENTITY_ID = "type/your-entity-id"; /** * 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 data) { String authToken = getAuthToken(); String endpoint = String.format("https://actions.googleapis.com/v2/apps/%s/entities/:batchPush", PROJECT_ID); JSONObject entity = new JSONObject(); entity.put("data", data.toString()); entity.put("name", String.format("apps/%s/entities/%s", PROJECT_ID, URLEncoder.encode(ENTITY_ID, "UTF-8"))); JSONObject request = new JSONObject(); request.put("entity", entity); JSONArray requestArray = new JSONArray(); requestArray.put(request); JSONObject payload = new JSONObject(); payload.put("requests", requestArray); payload.put("vertical", FOODORDERING); // Execute POST request executePostRequest(endpoint, authToken, payload); }
Elemente entfernen
Node.js
In diesem Code wird die Google-Authentifizierungsbibliothek für Node.js verwendet.
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
In diesem Code wird die Google-Authentifizierungsbibliothek für Python verwendet.
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
In diesem Code wird die Google-Authentifizierungsbibliothek für Java verwendet.
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)); }
Anwendungsfälle
Die folgenden Anwendungsfälle sind Beispiele für inkrementelle Aktualisierungen, vollständige Feedaktualisierungen, und den Inhalt auf übergeordneter Ebene im API-Aufruf:
Szenario | Zu aktualisierende Entität | Beschreibung und Effekte |
---|---|---|
Dienst deaktivieren | Service |
Sie müssen einen Dienst aus unvorhergesehenen Gründen deaktivieren. Inkrementelle Updates: Aktualisieren Sie die Entität Vollständige Feeds:Aktualisieren Sie die Entität über die vollständigen Feeds.
|
Bestimmter Artikel ist nicht auf Lager | MenuItemOffer |
Inkrementelle Updates: Senden Sie die kapselende MenuItemOffer .
Entität mit inventoryLevel auf 0 für die angegebene
MenuItem und alle anderen Daten unverändert. |
Preisänderung für Artikel auf der Speisekarte | MenuItemOffer |
Inkrementelle Updates: Senden Sie die kapselende MenuItemOffer .
Entität mit price auf den aktualisierten Preis für das angegebene
MenuItem und alle anderen Daten unverändert. |
Neues übergeordnetes Element hinzufügen Gilt nur für Entitätstypen |
Menu , Restaurant , Service |
Beispiel: Sie möchten einem Restaurant eine neue Speisekarte hinzufügen. Vollständige Feeds: Fügen Sie die Entität Ihren Datenfeeds hinzu und warten Sie auf die Batchaufnahme. |
Entität der obersten Ebene endgültig löschen Gilt nur für Entitätstypen |
Menu , Restaurant , Service |
Inkrementelle Updates:Senden Sie eine explizites Löschen. Vollständige Feeds:Entfernen Sie die Entität vor dem beim nächsten Abruf durch Google an. Andernfalls wird die Entität wieder hinzugefügt. |
Neues Liefergebiet in einer bestimmten Service hinzufügen |
ServiceArea |
Inkrementelle Feeds:Senden Sie die betreffende ServiceArea -Entität mit allen zugehörigen
mit neuem Liefergebiet, wie Sie es normalerweise bei den vollständigen Feeds tun würden.
die in polygon , geoRadius oder postalCode angegeben sind. |
Voraussichtliche Lieferzeit aktualisieren in Service |
ServiceHours |
Inkrementelle Feeds:Senden Sie ServiceHours wie in
die Feeds, außer der leadTimeMin , die aktualisiert wurde
entsprechend anpassen. |
Lieferpreise in Service aktualisieren |
Fee |
Inkrementelle Feeds:Vollständige Auslieferung Fee mit
price aktualisiert. |
Öffnungszeiten für Lieferung oder Essen zum Mitnehmen in Service aktualisieren |
ServiceHours |
Inkrementelle Feeds:Senden Sie ServiceHours wie in
Die Feeds mit Ausnahme der Eigenschaften opens und closes wurden aktualisiert.
entsprechend anpassen. |
Service (Mindestbestellwert ändern) |
Fee |
Inkrementelle Feeds:Vollständige Fee senden mit
minPrice
aktualisiert |
MenuItem endgültig löschen |
Menu |
Inkrementelle Feeds: Senden Sie die MenuItem wie im
-Feeds, aber parentMenuSectionId leer.
|
SLO für die Verarbeitungszeit für Batchjobs und inkrementelle Updates
Eine Entität, die durch einen Batch aktualisiert oder gelöscht wurde, wird innerhalb von zwei Stunden im Best-Effort-Modus, während eine über ein inkrementelles Update aktualisierte Entität in 5 Minuten. Eine veraltete Entität wird nach sieben Tagen gelöscht.
Sie können Google Folgendes senden:
- Mehrere Batchjobs pro Tag, um Ihr Inventar auf dem neuesten Stand zu halten, ODER
- Ein Batchjob pro Tag und inkrementelle APIs, um Ihr Inventar auf dem neuesten Stand zu halten