Bagian ini menjelaskan cara mengirimkan pembaruan feed yang sensitif terhadap waktu ke Google. API Pembaruan Tambahan memungkinkan Anda memperbarui dan menghapus entitas di feed hampir secara real time.
Fungsi ini ditujukan terutama untuk update yang tidak dapat Anda perkirakan, seperti penutupan darurat. Sebagai aturan, setiap perubahan yang dikirim melalui API Pembaruan Inkremental harus berupa perubahan yang harus diterapkan dalam waktu tidak lebih dari satu minggu. Jika perubahan tidak perlu segera ditampilkan, Anda dapat menggunakan update batch. Update inkremental diproses tidak lebih dari lima menit.
Penyiapan
Untuk menerapkan update inkremental, lakukan hal berikut:
- Ikuti langkah-langkah yang diuraikan dalam Membuat dan menyiapkan project untuk membuat project.
- Ikuti langkah-langkah yang diuraikan dalam Menyiapkan akun layanan untuk membuat akun layanan. Perhatikan bahwa Anda harus menjadi "Pemilik" project untuk menambahkan peran "Editor" untuk akun layanan
- (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 ini 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
Untuk memberi tahu Google tentang suatu update, buat permintaan POST HTTP ke API Inkremental Tambahan dan sertakan payload update dan penambahan. Skema inventaris yang Anda gunakan menentukan endpoint mana yang akan dibuat permintaan Anda:
inventaris v2
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID:push
inventaris v1
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/ENTITY_ID:push
Untuk menghapus entity, buat permintaan HTTP DELETE ke endpoint berikut yang sesuai dengan skema inventaris yang Anda gunakan:
inventaris v2
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
inventaris v1
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
Dalam permintaan di atas, ganti hal berikut:
- PROJECT_ID: Project ID Google Cloud yang terkait dengan project yang Anda buat di Membuat dan menyiapkan project.
- TYPE (khusus skema inventaris v2): Jenis entitas (properti
@type
) objek dalam feed data yang ingin diperbarui. - ENTITY_ID: ID entitas yang disertakan dalam payload. Pastikan untuk mengenkode URL ID entitas Anda.
- DELETE_TIME (hanya hapus endpoint): Kolom opsional untuk menunjukkan waktu penghapusan entity di sistem Anda (default-nya 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
untuk panggilan penghapusan. Format nilai ini sebagaiyyyy-mm-ddTHH:mm:ssZ
Misalnya, Anda memiliki project dengan ID "delivery-provider-id" yang menggunakan skema inventaris v2. Anda ingin membuat perubahan pada restoran dengan jenis entitas restoran "MenuSection" dan ID entitas "menuSection_122". Endpoint untuk pembaruan data Anda adalah sebagai berikut:
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122:push
Untuk menghapus entity yang sama, buat panggilan HTTP DELETE API ini:
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122?entity.vertical=FOODORDERING
Permintaan sandbox
Untuk permintaan sandbox, ikuti panduan di Endpoint di atas, tetapi
buat permintaan ke /v2/sandbox/apps/
, bukan ke /v2/apps/
. Misalnya, permintaan penghapusan sandbox untuk skema inventaris v2 disusun sebagai berikut:
https://actions.googleapis.com/v2/sandbox/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
Pembaruan dan penambahan
Feed batch harian Anda juga harus berisi perubahan yang dikirimkan melalui API ini. Jika tidak, pembaruan batch akan menimpa perubahan inkremental Anda.
Payload
Setiap permintaan POST harus menyertakan parameter permintaan beserta payload JSON yang berisi data terstruktur dari jenis entitas apa pun yang tercantum dalam skema inventaris.
JSON akan muncul sama seperti di feed batch, dengan perbedaan berikut:
- Isi payload tidak boleh melebihi 5 MB. Sama halnya dengan feed batch, sebaiknya Anda menghapus spasi kosong agar sesuai dengan lebih banyak data.
- Amplopnya adalah sebagai berikut:
{ "entity": { "data":"ENTITY_DATA", "vertical":"FOODORDERING" }, "update_time":"UPDATE_TIMESTAMP" }
Pada payload di atas, ganti hal 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
inkremental, pembuatan versi entity juga akan menggunakan
kolom
update_time
untuk permintaan add/update.
Mengupdate entity
Contoh 1: Memperbarui restoran
Misalnya Anda harus segera memperbarui nomor telepon restoran. 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 adalah sebagai berikut:
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" } }
Contoh 2: Memperbarui harga item menu
Misalkan Anda perlu mengubah harga item menu. Seperti pada Contoh 1, update harus berisi JSON untuk seluruh entity level 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, pembaruan inkremental Anda melalui POST adalah sebagai berikut:
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" } }
Menambahkan entity
Untuk menambahkan entitas, jangan gunakan pembaruan inventaris. Sebagai gantinya, gunakan proses feed batch seperti yang dijelaskan untuk skema inventaris v2.
Menghapus entity
Untuk menghapus entity level teratas, gunakan endpoint yang sedikit dimodifikasi, dan gunakan HTTP DELETE, bukan HTTP POST dalam permintaan.
Jangan gunakan HTTP DELETE untuk menghapus sub-entitas dalam entity level teratas, seperti item menu dalam menu. Perlakukan penghapusan sub-entity sebagai pembaruan pada entity level teratas yang menyebabkan sub-entity dihapus dari daftar atau parameter yang relevan.
Contoh 1: Menghapus entity tingkat teratas
Misalnya, Anda ingin menghapus restoran dalam feed yang menggunakan skema inventaris v1. Anda juga harus menghapus layanan dan menunya.
Contoh endpoint untuk entity menu dengan ID"https://www.provider.com/restaurant/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
Contoh endpoint untuk entitas restoran dengan ID "https://www.provider.com/restaurant/nr":
DELETE v2/apps/delivery-provider-id/entities/https%3A%2F%2Fwww.provider.com%2Frestaurant%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
Contoh endpoint untuk entity layanan dengan ID"https://www.provider.com/restaurant/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
}
Contoh 2: Menghapus sub-entity
Untuk menghapus sub-entitas dari dalam entity level teratas, Anda mengirimkan entity level teratas dengan sub-entity yang dihapus dari kolom yang sesuai. Contoh berikut mengasumsikan bahwa feed menggunakan skema inventaris v1.
Misalnya, untuk menghapus area layanan, perbarui layanan dengan area layanan yang dihapus dari daftar 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"
}
}
Kode respons API
Panggilan yang berhasil tidak berarti feed valid atau benar, hanya panggilan API yang dilakukan. Panggilan yang berhasil akan menerima kode respons HTTP 200, beserta isi respons kosong:
{}
Jika gagal, kode respons HTTP tidak akan menjadi 200, dan isi respons menunjukkan apa yang salah.
Misalnya, jika pengguna telah menyetel nilai "vertikal" di dalam amplopnya ke
FAKE_VERTICAL
, Anda akan menerima pesan berikut:
{
"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 ini adalah beberapa contoh cara menggunakan API Inkremental inkremental dalam berbagai bahasa. Contoh ini menggunakan Library Google Auth, 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 = '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
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 = '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
Kode ini menggunakan library autentikasi Google untuk 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); }
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 update inkremental, update feed lengkap, dan konten secara umum dalam panggilan API:
Skenario | Entitas tingkat teratas | Deskripsi dan efek |
---|---|---|
Menonaktifkan layanan | DisabledService |
Anda perlu menonaktifkan layanan karena alasan yang tidak terduga. Update inkremental: Kirim entity Feed lengkap: Pastikan untuk memperbarui entitas dari feed lengkap agar |
Stok item tertentu habis | Menu |
Update inkremental: Mengirim entity Menu enkapsulasi dengan offer.inventoryLevel yang ditetapkan ke 0 untuk MenuItem yang ditentukan, dan semua data lainnya tidak berubah. |
Perubahan harga item menu | Menu |
Update inkremental: Mengirim entity Menu enkapsulasi dengan offer.price yang ditetapkan ke harga terbaru untuk MenuItem yang ditentukan, dan semua data lainnya tidak berubah. |
Tambahkan entitas tingkat teratas baru Hanya berlaku untuk entity jenis |
Menu , Restaurant , Service |
Misalnya, Anda perlu menambahkan menu baru ke restoran. Update inkremental: Mengirim entity menu baru, beserta entity
restoran beserta kolomnya |
Menghapus entitas tingkat teratas secara permanen Hanya berlaku untuk entity jenis |
Menu , Restaurant , Service |
Update inkremental: Kirimkan 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 |
Service |
Feed inkremental: Kirim entity Service yang dimaksud dengan semua kolomnya tetap utuh, seperti yang biasa Anda lakukan dalam feed lengkap, dengan area pengiriman baru yang ditentukan dalam areaServed dari Service . |
Perbarui perkiraan waktu tiba di Service |
Service |
Feed inkremental: Kirim Service yang sama seperti dalam
feed, kecuali hoursAvailable.deliveryHours -nya
diperbarui sebagaimana mestinya. |
Perbarui harga pengiriman dalam Service |
Service |
Feed inkremental: Kirim Service lengkap dengan
offers.priceSpecification.price yang diperbarui. |
Perbarui jam pengiriman atau pengeksporan dalam Service |
Service |
Feed inkremental: Kirim Service yang sama seperti dalam
feed, kecuali hoursAvailable -nya
diperbarui sebagaimana mestinya. |
Service (ubah jumlah pesanan minimum) |
Service |
Feed inkremental: Kirim Service lengkap dengan
Service.offers.priceSpecification.eligibleTransactionVolume
diperbarui |
Hapus MenuItem secara permanen |
Menu |
Feed inkremental: Kirim Menu yang sama seperti dalam
feed, tetapi dengan MenuItem ini dihapus dari
daftar hasMenuItems . |
SLO pada waktu pemrosesan untuk tugas batch dan pembaruan inkremental
Entity yang ditambahkan melalui batch atau update inkremental akan diproses dalam 1-2 hari. Entity yang diupdate atau dihapus melalui batch akan diproses dalam 2 jam, sedangkan entity yang diperbarui melalui update inkremental akan diproses dalam 5 menit. Entitas usang akan dihapus dalam 7 hari.
Anda dapat mengirimkan ke Google:
- Beberapa tugas batch per hari untuk menjaga agar inventaris Anda tetap terbaru, ATAU
- Satu tugas batch per hari dan API Tambahan untuk menjaga inventaris Anda tetap terbaru.