Bu bölümde, feed'lerinizin zamana bağlı güncellemelerini Google'a nasıl gönderebileceğiniz açıklanmaktadır. Incremental Updates API, feed'lerinizdeki varlıkları neredeyse gerçek zamanlı olarak güncellemenizi ve silmenizi sağlar.
Bu işlev temel olarak, acil durum kapanışları gibi öngörülemeyen güncellemelere yöneliktir. Kural olarak, Incremental Updates API aracılığıyla gönderilen tüm değişiklikler en geç bir hafta içinde yayınlanması gereken bir değişiklik olmalıdır. Değişikliğinizin hemen yansıtılması gerekmiyorsa bunun yerine toplu güncellemeyi kullanabilirsiniz. Ek güncellemeler en fazla beş dakika içinde işlenir.
Kurulum
Artımlı güncellemeleri uygulamak için aşağıdakileri yapın:
- Proje oluşturmak için Proje oluşturma ve ayarlama bölümünde açıklanan adımları uygulayın.
- Hizmet hesabı oluşturmak için Hizmet hesabı oluşturma sayfasında belirtilen adımları uygulayın. Hizmet hesabına "Düzenleyici" rolü eklemek için projenin "Sahibi" olmanız gerektiğini unutmayın.
- (İsteğe bağlı, ancak önerilir) API'yi çağırırken OAuth 2.0'ı kullanmayı kolaylaştırmak için Google İstemci kitaplığını istediğiniz dilde yükleyin. Aşağıda verilen kod örnekleri bu kitaplıkları kullanır. Aksi takdirde, Google API'lerine Erişmek için OAuth 2.0'ı Kullanma bölümünde açıklandığı gibi jeton değişimlerini manuel olarak gerçekleştirmeniz gerekir.
Uç nokta
Google'a bir güncelleme bildirmek için Incremental Updates API'ye bir HTTP POST isteği gönderin ve güncellemeler ile eklemeler yükünü ekleyin. Kullandığınız envanter şeması, isteğinizin hangi uç noktaya yapılacağını belirler:
v2 envanteri
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID:push
v1 envanteri
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/ENTITY_ID:push
Bir varlığı kaldırmak için kullandığınız envanter şemasına karşılık gelen aşağıdaki uç noktaya HTTP DELETE isteği gönderin:
v2 envanteri
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
v1 envanteri
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
Yukarı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 (yalnızca v2 envanter şeması): Veri feed'inizdeki güncellemek istediğiniz nesnenin varlık türü (
@type
özelliği). - ENTITY_ID: Yüke dahil edilen varlığın kimliği. Varlık kimliğinizi URL ile kodladığınızdan emin olun.
- DELETE_TIME (yalnızca uç noktayı sil): Sistemlerinizde varlığın silindiği zamanı belirtmek için isteğe bağlı bir alandır (varsayılan olarak istek alındığı zamandır). Zaman değeri gelecekte olmamalıdır. Artımlı bir çağrı aracılığıyla bir varlık gönderirken varlık sürümü oluşturma, silme çağrısı durumunda
delete_time
alanını da kullanır. Bu değeriyyyy-mm-ddTHH:mm:ssZ
olarak biçimlendirin
Örneğin, v2 envanter şemasını kullanan "delivery-provider-id" kimliğine sahip bir projeniz var. Restoranda "MenüBölüm_122" varlık türü ve "MenüBölüm_122" varlık kimliği ile değişiklik yapmak istiyorsunuz. Verilerinizde yapılacak güncellemeler için uç nokta aşağıdaki gibidir:
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122:push
Aynı varlığı kaldırmak için şu HTTP DELETE API çağrısını yaparsınız:
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122?entity.vertical=FOODORDERING
Korumalı alan istekleri
Korumalı alan istekleri için yukarıdaki Uç nokta bölümünde yer alan kılavuzu izleyin ancak /v2/apps/
yerine /v2/sandbox/apps/
öğesine istek gönderin. Örneğin, v2 envanter şeması için bir korumalı alan silme isteği aşağıdaki gibi yapılandırılır:
https://actions.googleapis.com/v2/sandbox/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME
Güncellemeler ve eklemeler
Günlük toplu feed'leriniz, bu API üzerinden gönderilen tüm değişiklikleri de içermelidir. Aksi takdirde, toplu güncellemeleriniz artımlı değişikliklerinizin üzerine yazılır.
Yük
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üyle birlikte istek parametrelerini içermelidir.
JSON, aşağıdaki farklar dışında toplu feed'de olduğu gibi görünür:
- Yük gövdesinin 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ı öneririz.
- Zarf aşağıdaki gibidir:
{ "entity": { "data":"ENTITY_DATA", "vertical":"FOODORDERING" }, "update_time":"UPDATE_TIMESTAMP" }
Yukarıdaki yükte aşağıdakileri değiştirin:
- ENTITY_DATA: JSON biçiminde, dize olarak serileştirilmiş varlık. JSON-LD varlığı,
data
alanında bir dize olarak iletilmelidir. - UPDATE_TIMESTAMP (isteğe bağlı): Sistemlerinizde varlığın güncellendiği zaman damgası. Zaman değeri gelecekte olmamalıdır. Varsayılan zaman damgası, Google'ın isteği aldığı zamandır. Artımlı bir istek aracılığıyla varlık gönderirken varlık sürümü oluşturma, ekleme/güncelleme isteğinde de
update_time
alanını kullanır.
Varlık güncelleme
1. Örnek: Bir restoranı güncelleme
Bir restoranın telefon numarasını acilen güncellemeniz gerektiğini varsayalım. Güncellemeniz tüm restorana ait JSON dosyasını içerir.
Aşağıdaki gibi görünen bir toplu feed düşünün:
{ "@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 şöyle olur:
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" } }
2. Örnek: Menü öğesi fiyatını güncelleme
Menüdeki bir ürünün fiyatını değiştirmeniz gerektiğini varsayalım. 1. Örnek'te olduğu gibi, güncellemeniz üst düzey varlığın (menü) tamamı için JSON'u içermelidir ve feed, v1 envanter şemasını kullanır.
Aşağıdaki gibi görünen bir toplu feed düşünün:
{ "@type": "MenuItemOffer", "@id": "menuitemoffer6680262", "sku": "offer-cola", "menuItemId": "menuitem896532", "price": 3.00, "priceCurrency": "USD" }
Bu durumda POST aracılığıyla artımlı güncellemeniz aşağıdaki gibi olur:
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" } }
Varlık ekleme
Varlık eklemek için envanter güncellemeleri kullanmaktan kaçının. Bunun yerine, v2 envanter şeması için açıklandığı şekilde toplu feed işlemini kullanın.
Varlık kaldırma
Üst düzey varlıkları kaldırmak için, hafif değiştirilmiş bir uç nokta kullanır ve istekte HTTP POST yerine HTTP DELETE kullanabilirsiniz.
Üst düzey varlık içindeki bir alt varlığı (ör. menü içindeki bir menü öğesi) kaldırmak için HTTP DELETE'i kullanmayın. Bunun yerine, alt varlıkların kaldırılmasını, alt varlığın ilgili listeden veya parametreden kaldırıldığı üst düzey bir varlık için yapılan bir güncelleme olarak değerlendirin.
1. Örnek: Üst düzey öğeyi silme
v1 envanter şemasını kullanan bir feed'deki restoranı silmek istediğiniz bir durumu düşünün. Hizmetlerini ve menülerini de silmeniz gerekir.
"https://www.provider.com/Restaurant/menu/nr" kimliğine sahip bir menü varlığı için örnek uç nokta:
DELETE v2/apps/delivery-provider-id/entities/https%3A%2F%2Fwww.provider.com%2Frestaurant%2Fmenu%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
"https://www.provider.com/Restaurant/nr" kimliğine sahip bir restoran varlığı için örnek uç nokta:
DELETE v2/apps/delivery-provider-id/entities/https%3A%2F%2Fwww.provider.com%2Frestaurant%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
"https://www.provider.com/Restaurant/service/nr" kimliğine sahip bir hizmet varlığı için örnek uç nokta:
DELETE v2/apps/delivery-provider-id/entities/https%3A%2F%2Fwww.provider.com%2Frestaurant%2Fservice%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
}
2. Örnek: Alt varlıkları kaldırma
Bir alt varlığı üst düzey bir varlıktan kaldırmak için üst düzey öğeyi ilgili alandan alt varlığı kaldırarak gönderirsiniz. Aşağıdaki örnekte, feed'in v1 envanter şemasını kullandığı varsayılmaktadır.
Örneğin, bir hizmet bölgesini kaldırmak için hizmeti, areaServed
listesinden kaldırarak hizmet bölgesiyle güncelleyin.
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"
}
}
API yanıt kodları
Başarılı bir çağrı, feed'in geçerli veya doğru olduğu değil, 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 bir HTTP yanıt kodu 200 alır:
{}
Hatalar için HTTP yanıt kodu 200 olmaz ve yanıt gövdesinde neyin yanlış olduğu belirtilir.
Örneğin, kullanıcı zarftaki "vertical" değerini FAKE_VERTICAL
olarak ayarladıysa 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, Incremental Updates API'nin çeşitli dillerde nasıl kullanılacağına dair bazı örnekler verilmiştir. Bu örneklerde Google Kimlik Doğrulama Kitaplıkları kullanılı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 sayfasına bakın.
Varlıklar güncelleniyor
Node.js
Bu kod, Node.js için Google kimlik doğrulama kitaplığını kullanı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 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
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 = '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
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 = "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); }
Varlıkları kaldırma
Node.js
Bu kod, Node.js için Google kimlik doğrulama kitaplığını kullanı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ı; artımlı güncellemeler, tam feed güncellemeleri ve API çağrısındaki üst düzeydeki içeriğe örneklerdir:
Senaryo | Üst düzey öğe | Açıklama ve efektler |
---|---|---|
Bir hizmeti devre dışı bırakma | DisabledService |
Beklenmeyen bir nedenden dolayı bir hizmeti devre dışı bırakmanız gerekiyorsa. Ek güncellemeler: Tam feed'ler: Tam feed'lerdeki varlığı, Google tarafından bir sonraki getirme işleminden önce |
Belirli bir ürün stokta yok | Menu |
Ek güncellemeler: Kapsayıcı Menu varlığını, belirtilen MenuItem için offer.inventoryLevel değeri 0 olarak ayarlanmış şekilde, diğer tüm verileri değiştirmeden gönderin. |
Menü öğesi fiyat değişikliği | Menu |
Artımlı güncellemeler: offer.price içeren kapsayıcı Menu varlığını, belirtilen MenuItem için güncellenmiş fiyata ayarlayın ve diğer tüm verileri değiştirmeden gönderin. |
Yeni üst düzey öğe ekle Yalnızca |
Menu , Restaurant Service |
Örneğin, bir restorana yeni bir menü eklemeniz gerekiyor. Ek güncellemeler: Yeni menü öğesini, |
Üst düzey öğeyi kalıcı olarak silme Yalnızca |
Menu , Restaurant Service |
Ek güncellemeler: Açık silme gönderin. Tam feed'ler: Google tarafından bir sonraki getirme işleminden önce varlığı tam feed'lerden kaldırdığınızdan emin olun. Aksi takdirde öğe yeniden eklenir. |
Belirli bir Service alanına yeni teslimat bölgesi ekleyin |
Service |
Ek feed'ler: Söz konusu Service varlığını, tam feed'lerde yaptığınız gibi tüm alanları korunarak gönderin ve yeni yayınlama alanı areaServed içinde Service içinde belirtilir. |
Service konumunda teslimat için tahmini varış zamanını güncelleyin |
Service |
Ek feed'ler: Service öğesini, feed'lerdekiyle aynı şekilde gönderin ancak hoursAvailable.deliveryHours buna uygun şekilde güncellenir. |
Service ayındaki teslimat fiyatlarını güncelle |
Service |
Ek feed'ler: offers.priceSpecification.price güncellenmiş olarak tüm Service öğelerini gönderin. |
Service konumunda teslimat veya paket servisi saatlerini güncelleyin |
Service |
Ek feed'ler: Service öğesini, feed'lerdekiyle aynı şekilde gönderin ancak hoursAvailable buna uygun şekilde güncellenir. |
Service (min. sipariş tutarını değiştir) |
Service |
Ek feed'ler: Service adlı paketin tamamını (Service.offers.priceSpecification.eligibleTransactionVolume ) güncellenmiş olarak gönder |
MenuItem dosyasını kalıcı olarak sil |
Menu |
Ek feed'ler: Menu öğesini, feed'lerdekiyle aynı şekilde gönderin, ancak bu MenuItem öğesi hasMenuItems listesinden kaldırıldığında. |
Toplu işler ve artımlı güncellemeler için işleme süresiyle ilgili hizmet düzeyi hedefi
Toplu veya artımlı güncelleme yoluyla eklenen bir varlık 1-2 gün içinde işlenir. Toplu güncellemeyle güncellenen veya silinen bir varlık 2 saat içinde işlenir. Artımlı güncellemeyle güncellenen bir varlık ise 5 dakika içinde işlenir. Eski bir varlık 7 gün içinde silinir.
Google'a şu yöntemlerden birini gönderebilirsiniz:
- Envanterinizi güncel tutmak için günde birden fazla toplu iş YA DA
- Günde bir toplu iş ve envanterinizi güncel tutmak için Artımlı API'ler.