Bu bölümde, envanter öğelerinizle ilgili zamana duyarlı güncellemeleri Google'a nasıl gönderebileceğiniz açıklanmaktadır. Artımlı Güncelleme API'si, korumalı alan veya üretim envanterinizdeki öğeleri neredeyse gerçek zamanlı olarak güncellemenize ve silmenize olanak tanır.
Bu işlev, acil durum kapanışları gibi önceden tahmin edemeyeceğiniz güncellemeler için tasarlanmıştır. Kural olarak, Artımlı Güncelleme API'si aracılığıyla gönderilen tüm değişiklikler en fazla bir saat içinde yayınlanmalıdır. Değişikliklerinizin hemen yansıtılması gerekmiyorsa bunun yerine toplu beslemeyi kullanabilirsiniz. Artımlı güncellemeler en fazla beş dakika içinde işlenir.
Ön koşullar
Artımlı güncellemeleri uygulamadan önce aşağıdakiler gereklidir:
- Actions projenizde düzenleyici rolüne sahip bir hizmet hesabı oluşturulur. Daha fazla bilgi için Proje oluşturma ve ayarlama başlıklı makaleyi inceleyin.
- Üretim veya korumalı alan veri feed'leri barındırılır ve beslenir. Daha fazla bilgi için Toplu besleme bölümüne bakın.
- (İsteğe bağlı ancak önerilir) API'yi çağırırken OAuth 2.0'u kullanmayı kolaylaştırmak için Google istemci kitaplığını tercih ettiğiniz dilde yükleyin. Aşağıda verilen kod örnekleri bu kitaplıkları kullanır. Aksi takdirde, jeton değişimlerini Google API'lerine Erişmek için OAuth 2.0'ı Kullanma bölümünde açıklandığı gibi manuel olarak yapmanız gerekir.
Uç noktalar
Aşağıdaki isteklerde aşağıdakileri değiştirin:
- PROJECT_ID: Proje oluşturma ve ayarlama bölümünde oluşturduğunuz projeyle ilişkili Google Cloud proje kimliği.
- TYPE: Veri feed'inizde güncellemek istediğiniz nesnenin varlık türü (
@type
mülkü). - ENTITY_ID (yalnızca silme uç noktası): Silinecek öğenin kimliği. Varlık kimliğinizi URL kodladığınızdan emin olun.
- DELETE_TIME (yalnızca silme uç noktası): Öğenin sistemlerinizde silindiği zamanı belirtmek için kullanılan isteğe bağlı alan (varsayılan olarak istek alındığında). Zaman değeri gelecekte olmamalıdır. Öğe sürümlendirme, bir öğeyi artımlı çağrıyla gönderirken silme çağrısı durumunda
delete_time
alanını da kullanır. Bu değeriyyyy-mm-ddTHH:mm:ssZ
olarak biçimlendir
Uç noktayı güncelleme
Bir öğeyi değiştirmek için aşağıdaki uç noktaya bir HTTP POST isteği gönderin ve güncelleme ve eklemeler içeren bir yükü ekleyin. Tek bir API çağrısında 1.000'e kadar öğeyi güncelleyebilirsiniz.
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities:batchPush
Örneğin, "delivery-provider-id" kimlikli bir projedeki öğeleri güncellemek istiyorsanız uç nokta şu şekilde olur:
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities:batchpush
Uç noktayı silin
Envanterinizdeki bir öğeyi silmek için aşağıdaki uç noktaya bir HTTP DELETE isteği gönderin.
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
Örneğin, "menuSection_122" kimlikli bir "MenuSection" öğesini "delivery-provider-id" projenizden silmek için şuraya bir HTTP DELETE API çağrısı yaparsınız:
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122?entity.vertical=FOODORDERING
Korumalı alan ortamı
Korumalı alan envanterinizde Artımlı Güncelleme API'sini kullanmak için yukarıdaki Bitiş Noktaları bölümündeki talimatları uygulayın ancak /v2/apps/
yerine /v2/sandbox/apps/
adresine istek gönderin.
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
Varlıkları güncelleme
Her POST isteği, envanter şemasında listelenen herhangi bir varlık türünün yapılandırılmış verilerini içeren JSON yükü ile birlikte istek parametrelerini içermelidir.
Yükü güncelleme
JSON, aşağıdaki farklılıklarla birlikte toplu feed'de olduğu gibi görünür:
- Yük gövdesi boyutu 5 MB'ı aşmamalıdır. Toplu feed'lere benzer şekilde, daha fazla veri sığdırmak için boşlukları kaldırmanız önerilir.
- Zarf aşağıdaki gibidir:
{ "requests": [ { "entity": { "data":"ENTITY_DATA", "name": "apps/project_id>/entities/type/entity_id" }, "update_time":"UPDATE_TIMESTAMP" }, ], "vertical": "FOODORDERING" }
Yukarıdaki yükte aşağıdakileri değiştirin:
- ENTITY_DATA: JSON biçimindeki öğe, dize olarak serileştirilir. JSON-LD öğesi,
data
alanında dize olarak iletilmelidir. - UPDATE_TIMESTAMP (isteğe bağlı): Öğenin sistemlerinizde güncellendiği zaman damgası. Zaman değeri gelecekte olmamalıdır. Varsayılan zaman damgası, Google'ın isteği aldığı zamandır. Bir öğe artımlı istek aracılığıyla gönderilirken varlık sürümlendirme, ekleme/güncelleme isteği durumunda
update_time
alanını da kullanır.
Örnekler
Örnek 1: Bir restoranı güncelleme
Bir restoranın telefon numarasını acil olarak güncellemeniz gerektiğini varsayalım. Güncellemeniz, restoranın tamamının JSON'unu içerir.
Aşağıdaki gibi görünen bir toplu feed'i ele alalım:
{ "@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 }
Bu durumda, HTTP POST ile artımlı güncellemeniz aşağıdaki gibi olur:
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" }
2. Örnek: Birden fazla restoranı güncelleme
Tek bir API çağrısında iki restoran öğesini güncellemek için HTTP POST isteği aşağıdaki gibi olur:
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" }
3. örnek: Menü öğesi fiyatını güncelleme
Bir menü öğesinin fiyatını değiştirmeniz gerektiğini varsayalım. 1. örnekte olduğu gibi, güncellemeniz üst düzey öğenin (menünün) tamamının JSON'unu içermelidir ve feed, v1 envanter şemasını kullanır.
Aşağıdaki gibi görünen bir toplu feed'i ele alalım:
{ "@type": "MenuItemOffer", "@id": "menuitemoffer6680262", "sku": "offer-cola", "menuItemId": "menuitem896532", "price": 3.00, "priceCurrency": "USD" }
Bu durumda, POST üzerinden artımlı güncellemeniz aşağıdaki gibi olur:
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" }
Varlık ekleme
Öğe eklemek için envanter güncellemelerini kullanmaktan kaçının. Bunun yerine, v2 envanter şeması için açıklandığı gibi toplu feed'ler sürecini kullanın.
Bir öğeyi kaldırma
Üst düzey öğeleri kaldırmak için biraz değiştirilmiş bir bitiş noktası kullanır ve istekte HTTP POST yerine HTTP DELETE'yi kullanırsınız.
Üst düzey bir öğeyi silme
Bir feed'deki restoranı silmek istediğinizi varsayalım. Ayrıca, bu uygulamanın hizmetlerini ve menülerini de silmeniz gerekir.
"provider/restaurant/menu/nr" kimlikli bir menü öğesi için örnek uç nokta:
DELETE v2/apps/delivery-provider-id/entities/menu/provider%2Frestaurant%2Fmenu%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
"https://www.provider.com/restaurant/nr" kimlikli bir restoran öğesi için örnek uç nokta:
DELETE v2/apps/delivery-provider-id/entities/restaurant/provider%2Frestaurant%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
"https://www.provider.com/restaurant/service/nr" kimlikli bir hizmet öğesi için örnek uç nokta:
DELETE v2/apps/delivery-provider-id/entities/service/provider%2Frestaurant%2Fservice%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
}
Alt öğeleri kaldırma
Üst düzey bir öğedeki alt öğeyi (ör. bir menüdeki menü öğesi) kaldırmak için HTTP DELETE'yi kullanmayın. Bunun yerine, alt öğelerin kaldırılmasını, alt öğenin ilgili listeden veya reverseReference öğesinden kaldırıldığı bir üst düzey öğe güncellemesi olarak değerlendirin.
API yanıt kodları
Başarılı bir çağrı, feed'in geçerli veya doğru olduğu anlamına gelmez. Yalnızca API çağrısının yapıldığı anlamına gelir. Başarılı çağrılar, boş bir yanıt gövdesiyle birlikte 200 HTTP yanıt kodu alır:
{}
Başarısız işlemlerde HTTP yanıt kodu 200 olmaz ve yanıt gövdesinde hatanın ne olduğu belirtilir.
Örneğin, kullanıcı zarftaki "dikey" değerini FAKE_VERTICAL
olarak ayarlarsa aşağıdaki mesajı alırsınız:
{
"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\""
}
]
}
]
}
}
Kod örneği
Aşağıda, Artımlı Güncelleme API'sinin çeşitli dillerde nasıl kullanılacağına dair bazı örnekler verilmiştir. Bu örnekler Google Kimlik Doğrulama Kitaplıkları'nı kullanır ve v1 envanter şemasını kullanan bir feed varsayılır. Alternatif çözümler için Sunucudan Sunucuya Uygulamalar için OAuth 2.0'ı Kullanma bölümüne bakın.
Varlıkları güncelleme
Node.js
Bu kodda, Node.js için Google kimlik doğrulama kitaplığı kullanılmaktadır.
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
Bu kod, Python için Google kimlik doğrulama kitaplığını kullanır.
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
Bu kod, Java için Google kimlik doğrulama kitaplığını kullanır.
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); }
Öğeleri kaldırma
Node.js
Bu kodda, Node.js için Google kimlik doğrulama kitaplığı kullanılmaktadır.
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
Bu kod, Python için Google kimlik doğrulama kitaplığını kullanır.
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
Bu kod, Java için Google kimlik doğrulama kitaplığını kullanır.
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)); }
Kullanım alanları
Aşağıdaki kullanım alanları, kademeli güncellemelere, tam feed güncellemelerine ve API çağrısında yüksek düzeyde içeriğe örnektir:
Senaryo | Güncellenecek öğe | Açıklama ve etkiler |
---|---|---|
Bir hizmeti devre dışı bırakma | Service |
Bir hizmeti beklenmedik bir nedenle devre dışı bırakmanız gerekir. Artımlı güncellemeler: Söz konusu Tam feed'ler: Google'ın bir sonraki getirme işleminden önce |
Belirli bir öğe stokta yok | MenuItemOffer |
Artımlı güncellemeler: Kapsayan MenuItemOffer öğesini, belirli bir MenuItem için inventoryLevel 'ın 0 olarak ayarlandığı ve diğer tüm verilerin değişmediği şekilde gönderin. |
Menü öğesi fiyat değişikliği | MenuItemOffer |
Artımlı güncellemeler: Kapsülleme MenuItemOffer öğesini, price parametresi belirli bir MenuItem için güncellenmiş fiyata ayarlanmış ve diğer tüm veriler değişmeden gönderin. |
Yeni üst düzey öğe ekleme Yalnızca |
Menu , Restaurant , Service |
Örneğin, bir restorana yeni bir menü eklemeniz gerekiyor. Tam feed'ler: Varlıklarınızı veri feed'lerinize ekleyin ve toplu beslemeyi bekleyin. |
Üst düzey öğeyi kalıcı olarak silme Yalnızca |
Menu , Restaurant , Service |
Artımlı güncellemeler: Açık silme gönderin. Tam feed'ler: Google'ın bir sonraki getirme işleminden önce öğeyi tam feed'lerden kaldırdığınızdan emin olun. Aksi takdirde öğe yeniden eklenir. |
Belirli bir Service 'ye yeni teslimat bölgesi ekleme |
ServiceArea |
Artımlı feed'ler: Söz konusu ServiceArea öğesini, tüm alanlarıyla birlikte, normalde tam feed'lerde yaptığınız gibi polygon , geoRadius veya postalCode içinde belirtilen yeni teslimat alanıyla gönderin. |
Service için tahmini teslimat varış saatini güncelleme |
ServiceHours |
Artımlı feed'ler: leadTimeMin 'ın buna göre güncellenmesi dışında ServiceHours , feed'lerdekiyle aynı şekilde gönderilir. |
Service 'te teslimat fiyatlarını güncelleme |
Fee |
Artımlı feed'ler: price güncellenerek tam yayın Fee gönderin. |
Service 'te teslimat veya paket servisi çalışma saatlerini güncelleme |
ServiceHours |
Artımlı feed'ler: opens ve closes özellikleri uygun şekilde güncellendiğinden ServiceHours 'yi feed'lerdekiyle aynı şekilde gönderin. |
Service (minimum sipariş tutarını değiştirin) |
Fee |
Artımlı feed'ler: minPrice ile güncellenmiş tam Fee gönderin
|
MenuItem 'leri kalıcı olarak silme |
Menu |
Artımlı feed'ler: MenuItem öğesini feed'lerde olduğu gibi gönderin ancak parentMenuSectionId boş olsun.
|
Toplu işler ve artımlı güncellemeler için işlem süresiyle ilgili hizmet düzeyi hedefi
Bir toplu işlem aracılığıyla güncellenen veya silinen varlıklar, en iyi çaba modunda 2 saat içinde işlenir. Artımlı güncelleme aracılığıyla güncellenen varlıklar ise 5 dakika içinde işlenir. Eski öğeler 7 gün içinde silinir.
Google'a şu bilgileri gönderebilirsiniz:
- Envanterinizi güncel tutmak için günde birden fazla toplu iş VEYA
- Envanterinizi güncel tutmak için günde bir toplu iş ve artımlı API'ler.