Bagian ini menjelaskan cara mengirim pembaruan yang sensitif terhadap waktu dari entity inventaris Anda ke Google. Incremental Update API memungkinkan Anda mendorong update dan menghapus entity di inventaris Sandbox atau Produksi secara hampir real time.
Fungsi ini terutama ditujukan untuk update yang tidak dapat Anda prediksi, seperti penutupan darurat. Sebagai aturan, setiap perubahan yang dikirimkan melalui Incremental Update API harus berupa perubahan yang harus ditayangkan dalam waktu tidak lebih dari satu jam. Jika perubahan tidak perlu segera diterapkan, Anda dapat menggunakan penyerapan batch sebagai gantinya. Update inkremental diproses dalam waktu tidak lebih dari lima menit.
Prasyarat
Item berikut diperlukan sebelum Anda menerapkan update inkremental:
- Akun layanan dibuat dengan peran editor untuk project Actions Anda. Untuk mengetahui detail selengkapnya, lihat Membuat dan menyiapkan project.
- Feed data produksi atau sandbox dihosting dan diserap. Untuk mengetahui detail selengkapnya, lihat Penyerapan batch.
- (Opsional, tetapi direkomendasikan) Instal library Klien Google dalam bahasa pilihan Anda untuk memfasilitasi penggunaan OAuth 2.0 saat memanggil API. Contoh kode yang disertakan di bawah menggunakan library ini. Jika tidak, Anda harus menangani pertukaran token secara manual seperti yang dijelaskan dalam Menggunakan OAuth 2.0 untuk Mengakses Google API.
Endpoint
Dalam permintaan di bawah, ganti hal berikut:
- PROJECT_ID: Project ID Google Cloud yang terkait dengan project yang Anda buat di Membuat dan menyiapkan project.
- TYPE: Jenis entity (properti
@type
) objek dalam feed data yang ingin Anda perbarui. - ENTITY_ID (khusus endpoint hapus): ID entitas yang akan dihapus. Pastikan untuk mengenkode ID entitas Anda ke dalam URL.
- DELETE_TIME (khusus endpoint hapus): Kolom opsional untuk menunjukkan
waktu entitas dihapus di sistem Anda (defaultnya adalah saat permintaan
diterima). Nilai waktu tidak boleh di masa mendatang. Saat mengirim entity melalui panggilan inkremental, pembuatan versi entity juga menggunakan kolom
delete_time
jika terjadi panggilan penghapusan. Format nilai ini sebagaiyyyy-mm-ddTHH:mm:ssZ
Memperbarui endpoint
Untuk mengubah entity, buat permintaan POST HTTP ke endpoint berikut dan sertakan payload pembaruan dan penambahan. Anda dapat melakukan pembaruan hingga 1.000 entity dalam satu panggilan API.
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities:batchPush
Misalnya, jika Anda ingin memperbarui entity dalam project dengan ID "delivery-provider-id", endpoint-nya adalah sebagai berikut:
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities:batchpush
Menghapus endpoint
Untuk menghapus entity di inventaris, buat permintaan HTTP DELETE ke endpoint berikut.
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
Misalnya, untuk menghapus entitas "MenuSection" dengan ID "menuSection_122" dari project "delivery-provider-id", Anda harus membuat panggilan API HTTP DELETE ke:
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122?entity.vertical=FOODORDERING
Lingkungan sandbox
Untuk menggunakan Incremental Update API di inventaris sandbox, ikuti panduan di Endpoint di atas, tetapi
buat permintaan ke /v2/sandbox/apps/
, bukan ke /v2/apps/
.
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
Mengupdate entity
Setiap permintaan POST harus menyertakan parameter permintaan beserta payload JSON yang berisi data terstruktur dari jenis entity apa pun yang tercantum dalam skema inventaris.
Memperbarui payload
JSON akan terlihat sama seperti di feed batch, dengan perbedaan berikut:
- Ukuran isi payload tidak boleh melebihi 5 MB. Serupa dengan feed batch, sebaiknya hapus spasi kosong agar lebih banyak data yang muat.
- Envelopnya adalah sebagai berikut:
{ "requests": [ { "entity": { "data":"ENTITY_DATA", "name": "apps/project_id>/entities/type/entity_id" }, "update_time":"UPDATE_TIMESTAMP" }, ], "vertical": "FOODORDERING" }
Dalam payload di atas, ganti kode berikut:
- ENTITY_DATA: Entitas dalam format JSON yang diserialisasi sebagai string. Entitas
JSON-LD harus diteruskan sebagai string di kolom
data
. - UPDATE_TIMESTAMP (opsional): Stempel waktu saat entity diperbarui di
sistem Anda. Nilai waktu tidak boleh di masa mendatang. Stempel waktu default adalah saat
Google menerima permintaan. Saat mengirim entity melalui permintaan tambahan, pembuatan versi entity juga menggunakan kolom
update_time
jika ada permintaan penambahan/pembaruan.
Contoh
Contoh 1: Memperbarui restoran
Misalnya, Anda perlu memperbarui nomor telepon restoran dengan segera. Pembaruan Anda berisi JSON untuk seluruh restoran.
Pertimbangkan feed batch yang terlihat seperti berikut:
{ "@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 }
Kemudian, pembaruan inkremental Anda melalui HTTP POST akan menjadi seperti berikut:
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" }
Contoh 2: Memperbarui beberapa restoran
Untuk memperbarui dua entitas restoran dalam satu panggilan API, permintaan POST HTTP akan menjadi seperti berikut:
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" }
Contoh 3: Memperbarui harga item menu
Misalnya, Anda perlu mengubah harga item menu. Seperti pada Contoh 1, pembaruan Anda harus berisi JSON untuk seluruh entitas tingkat teratas (menu), dan feed menggunakan skema inventaris v1.
Pertimbangkan feed batch yang terlihat seperti berikut:
{ "@type": "MenuItemOffer", "@id": "menuitemoffer6680262", "sku": "offer-cola", "menuItemId": "menuitem896532", "price": 3.00, "priceCurrency": "USD" }
Kemudian, update inkremental Anda melalui POST akan menjadi seperti berikut:
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" }
Menambahkan entity
Untuk menambahkan entity, hindari penggunaan update inventaris. Sebagai gantinya, gunakan proses feed batch seperti yang dijelaskan untuk skema inventaris v2.
Menghapus entity
Untuk menghapus entitas tingkat atas, Anda menggunakan endpoint yang sedikit dimodifikasi, dan menggunakan HTTP DELETE, bukan HTTP POST dalam permintaan.
Menghapus entity tingkat teratas
Pertimbangkan situasi saat Anda ingin menghapus restoran di feed. Anda juga harus menghapus layanan dan menunya.
Contoh endpoint untuk entitas menu dengan ID "provider/restaurant/menu/nr":
DELETE v2/apps/delivery-provider-id/entities/menu/provider%2Frestaurant%2Fmenu%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
Contoh endpoint untuk entitas restoran dengan 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
Contoh endpoint untuk entitas layanan dengan 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
}
Menghapus sub-entity
Jangan gunakan HTTP DELETE untuk menghapus sub-entity dalam entity tingkat teratas, seperti item menu dalam menu. Sebagai gantinya, perlakukan penghapusan sub-entity sebagai update ke entitas level atas tempat sub-entity dihapus dari daftar yang relevan atau reverseReference.
Kode respons API
Panggilan yang berhasil tidak berarti bahwa feed valid atau benar, hanya bahwa panggilan API telah dilakukan. Panggilan yang berhasil akan menerima kode respons HTTP 200, beserta isi respons kosong:
{}
Untuk kegagalan, kode respons HTTP tidak akan menjadi 200, dan isi respons menunjukkan masalah yang terjadi.
Misalnya, jika pengguna telah menetapkan nilai "vertical" dalam amplop ke
FAKE_VERTICAL
, Anda akan menerima pesan di bawah ini:
{
"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\""
}
]
}
]
}
}
Contoh kode
Berikut adalah beberapa contoh cara menggunakan Incremental Update API dalam berbagai bahasa. Contoh ini menggunakan Library Autentikasi Google, dan mengasumsikan feed menggunakan skema inventaris v1. Untuk solusi alternatif, lihat Menggunakan OAuth 2.0 untuk Aplikasi Server ke Server.
Mengupdate entity
Node.js
Kode ini menggunakan library autentikasi Google untuk 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 = '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
Kode ini menggunakan library autentikasi Google untuk 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 = '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
Kode ini menggunakan library autentikasi Google untuk Java.
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); }
Menghapus entity
Node.js
Kode ini menggunakan library autentikasi Google untuk 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
Kode ini menggunakan library autentikasi Google untuk 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
Kode ini menggunakan library autentikasi Google untuk 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)); }
Kasus penggunaan
Kasus penggunaan berikut adalah contoh pembaruan inkremental, pembaruan feed lengkap, dan konten di tingkat tinggi dalam panggilan API:
Skenario | Entitas yang akan diperbarui | Deskripsi dan efek |
---|---|---|
Menonaktifkan layanan | Service |
Anda perlu menonaktifkan layanan karena alasan yang tidak terduga. Update inkremental: Perbarui entitas Feed lengkap: Pastikan untuk memperbarui entitas dari feed lengkap
agar |
Stok item tertentu habis | MenuItemOffer |
Pembaruan inkremental: Kirim entitas MenuItemOffer
yang mengenkapsulasi dengan inventoryLevel ditetapkan ke 0 untuk
MenuItem yang diberikan, dan semua data lainnya tidak berubah. |
Perubahan harga item menu | MenuItemOffer |
Pembaruan inkremental: Kirim entity MenuItemOffer
yang mengenkapsulasi dengan price ditetapkan ke harga yang diperbarui untuk
MenuItem tertentu, dan semua data lainnya tidak berubah. |
Menambahkan entity tingkat teratas baru Hanya berlaku untuk entity jenis |
Menu , Restaurant , Service |
Misalnya, Anda perlu menambahkan menu baru ke restoran. Feed lengkap: Tambahkan entity di feed data Anda dan tunggu penyerapan batch. |
Menghapus entity tingkat teratas secara permanen Hanya berlaku untuk entity jenis |
Menu , Restaurant , Service |
Update inkremental: Kirim penghapusan eksplisit. Feed lengkap: Pastikan untuk menghapus entitas dari feed lengkap sebelum pengambilan berikutnya oleh Google. Jika tidak, entitas akan ditambahkan kembali. |
Menambahkan area pengiriman baru di Service tertentu |
ServiceArea |
Feed inkremental: Kirim entity ServiceArea yang dimaksud dengan semua
kolomnya tetap utuh, seperti yang biasa Anda lakukan dalam feed lengkap, dengan area pengiriman baru
yang ditentukan dalam polygon , geoRadius , atau postalCode . |
Memperbarui perkiraan waktu tiba pengiriman di Service |
ServiceHours |
Feed inkremental: Kirim ServiceHours yang sama seperti di
feed, kecuali leadTimeMin -nya diperbarui
sebagaimana mestinya. |
Memperbarui harga pengiriman di Service |
Fee |
Feed inkremental: Mengirim pengiriman lengkap Fee dengan
price yang diperbarui. |
Memperbarui jam buka untuk pesan antar atau bawa pulang di Service |
ServiceHours |
Feed inkremental: Kirim ServiceHours yang sama seperti di
feed, kecuali properti opens dan closes -nya diperbarui
sebagaimana mestinya. |
Service (ubah jumlah pesanan minimum) |
Fee |
Feed inkremental: Mengirim Fee lengkap dengan
minPrice
yang diperbarui |
Menghapus MenuItem secara permanen |
Menu |
Feed inkremental: Kirim MenuItem yang sama seperti di
feed, tetapi dengan parentMenuSectionId kosong.
|
SLO tentang waktu pemrosesan untuk tugas batch dan update inkremental
Entitas yang diperbarui atau dihapus melalui batch akan diproses dalam waktu 2 jam dalam mode upaya terbaik, sedangkan entitas yang diperbarui melalui update inkremental akan diproses dalam 5 menit. Entitas yang tidak berlaku akan dihapus dalam 7 hari.
Anda dapat mengirimkan ke Google:
- Beberapa tugas batch per hari untuk terus memperbarui inventaris Anda, ATAU
- Satu tugas batch per hari dan Incremental API untuk terus memperbarui inventaris Anda.