Bu bölümde, envanterinizin zamana duyarlı güncellemelerini nasıl gönderebileceğiniz açıklanmaktadır. varlıkları Google'a iletebiliriz. Artımlı Güncelleme API'si, güncellemeleri aktarmanıza ve Korumalı Alan veya Üretim envanterinizdeki varlıkları neredeyse gerçek zamanlı olarak gösterir.
Bu işlev temel olarak, sizin öngöremediğiniz güncellemeler için tasarlanmıştır, örneğin acil durum kapatmaları gibi. Kural olarak, Artımlı Güncelleme API'sı en geç bir saat. Değişikliğinizin hemen uygulanması gerekmiyorsa, toplu besleme yöntemini kullanabilirsiniz. Artımlı güncellemeler en fazla beş dakika içinde işlenir.
Ön koşullar
Artımlı güncellemeleri uygulamadan önce aşağıdakilerin yerine getirilmesi gerekir:
- Actions projenizde düzenleyici rolüyle bir hizmet hesabı oluşturulur. Daha fazla bilgi için Proje oluşturun.
- Üretim veya korumalı alan veri feed'leri barındırılır ve kullanılır. Daha fazla bilgi için Toplu besleme.
- (İsteğe bağlı, ancak önerilir) Google istemci kitaplığını yükleyin API'ye gidin. 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 konusunda açıklandığı gibi manuel olarak gerçekleştirmeniz gerekir.
Uç noktalar
Aşağıdaki isteklerde, aşağıdakileri değiştirin:
- PROJECT_ID: Projenizle ilişkili Google Cloud proje kimliği Proje oluşturma ve ayarlama bölümünde oluşturulur.
- TYPE: Varlık türü (
@typeözelliği) veri feed'inizde güncellemek istediğiniz nesnenin. - ENTITY_ID (yalnızca uç noktayı sil): Silinecek varlığın kimliği. Şunları yaptığınızdan emin olun: URL, varlık kimliğinizi kodlar.
- DELETE_TIME (yalnızca uç noktayı sil):
varlığın sistemlerinizde silindiği zaman (varsayılan olarak, isteğin
alınmıştır). Zaman değeri gelecekte olmamalıdır. Bir varlık gönderirken
artımlı çağrı ile varlık sürümü oluşturma
silme çağrısında
delete_timealanını da kullanır. Bunu biçimlendiryyyy-mm-ddTHH:mm:ssZolarak değer
Uç noktayı güncelleme
Bir varlığı değiştirmek için aşağıdaki uç noktaya HTTP POST isteği gönderin ve güncellemeler ile eklemeler yükü dahil eder. Tek bir API çağrısında en fazla 1.000 varlıkta güncelleme yapabilirsiniz.
https://actions.googleapis.com/v2/apps/PROJECT_ID/entities:batchPush
Örneğin, bir projedeki varlıkları "delivery-provider-id" kimliğiyle güncellemek isterseniz. uç nokta şöyle olur:
https://actions.googleapis.com/v2/apps/delivery-provider-id/entities:batchpush
Uç noktayı silin
Envanterinizdeki bir varlığı silmek için aşağıdaki uç noktaya 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, bir "MenüBölümü"nü silmek için "menuSection_122" kimliğine sahip varlık "delivery-provider-id"nizden şuna 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 Uç Noktalar bölümünde belirtilen kılavuzu uygulayın ancak
/v2/apps/ yerine /v2/sandbox/apps/ isteğinde bulun.
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, JSON ile birlikte istek parametrelerini içermelidir envanter şeması.
Yükü güncelleyin
JSON dosyası, şu farklılıklar var:
- Yük gövdesinin boyutu 5 MB'ı aşmamalıdır. Toplu işleme benzer daha fazla veri sığdırmak için boşlukları kaldırmanızı öneririz.
- Zarf şöyle:
{ "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ğıdakini değiştirin:
- ENTITY_DATA: Dize olarak serileştirilmiş JSON biçiminde varlık. İlgili içeriği oluşturmak için kullanılan
JSON-LD varlığı,
dataalanında dize olarak geçirilmelidir. - UPDATE_TIMESTAMP (isteğe bağlı): Öğenin güncellenme zaman damgası
nasıl sağlayabileceğini de öğreneceksiniz. Zaman değeri gelecekte olmamalıdır. Varsayılan zaman damgası:
Google isteği alır. Bir varlığı artımlı
isteği yerine getirildiğinde, varlık sürümü oluşturma özelliği de
update_timealanına girilen değeri gösterir.
Örnekler
1. Örnek: Bir restoranı güncelleme
Bir restoranın telefon numarasını acilen güncellemeniz gerektiğini varsayalım. Sizin güncelleme, tüm restoran için JSON dosyasını içerir.
Aşağıdaki gibi görünen bir toplu feed kullanmayı düşünebilirsiniz:
{ "@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 }
HTTP POST üzerinden yapılan 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 varlığını 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ü seçeneği fiyatını güncelleme
Bir menü öğesinin fiyatını değiştirmeniz gerektiğini varsayalım. 1. Örnek’te olduğu gibi, güncelleme, tüm üst düzey varlığın (menü) JSON dosyasını ve feed, v1 envanter şemasını kullanır.
Aşağıdaki gibi görünen bir toplu feed kullanmayı düşünebilirsiniz:
{ "@type": "MenuItemOffer", "@id": "menuitemoffer6680262", "sku": "offer-cola", "menuItemId": "menuitem896532", "price": 3.00, "priceCurrency": "USD" }
POST aracılığıyla artımlı güncellemeniz aşağıdaki gibi olacaktır:
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
Varlık eklemek için envanter güncellemeleri kullanmaktan kaçının. Bunun yerine, v2 envanter şemasında açıklandığı gibi işleme devam edin.
Varlık kaldırma
Üst düzey öğeleri kaldırmak için biraz değiştirilmiş bir uç nokta kullanırsınız. ve istekte HTTP POST yerine HTTP DELETE kullanın.
Üst düzey öğeyi silme
Feed'deki bir restoranı silmek istediğiniz durumu düşünün. Şunu yapmalısınız: ayrıca hizmetlerini ve menülerini de siler.
Kimliği olan bir menü öğesi için örnek uç nokta "provider/restaurant/menu/nr":
DELETE v2/apps/delivery-provider-id/entities/menu/provider%2Frestaurant%2Fmenu%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
Kimliği olan bir restoran varlığı için örnek uç nokta "https://www.provider.com/restaurant/nr":
DELETE v2/apps/delivery-provider-id/entities/restaurant/provider%2Frestaurant%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com
Kimliği olan bir hizmet varlığı için örnek uç nokta "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
}
Alt varlıkları kaldırma
Aşağıdaki gibi üst düzey bir varlık içindeki bir alt varlığı kaldırmak için HTTP DELETE komutunu kullanmayın. bir menü öğesi bulunuyor. Bunun yerine, alt varlıkların kaldırılmasını bir üst düzey öğeye yapılan güncellemenin ardından, alt öğe, alakalı liste veya reverseReference ile
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ı yapıldı. Başarılı çağrılara HTTP yanıt kodu 200'ün yanı sıra yerine boş bir yanıt gövdesiyle değiştirin:
{}
Hatalar için HTTP yanıt kodu 200 olmaz ve yanıt gövdesi sorunun ne olduğunu gösterir.
Örneğin, kullanıcı "tema"yı ayarlamışsa zarfın içindeki değeri
FAKE_VERTICAL, 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 cihazlarda nasıl kullanılacağına dair dil. Bu örneklerde Google Kimlik Doğrulama Kitaplıkları kullanılmaktadır ve v1 envanter şeması. Alternatif çözümler için Sunucudan Sunucuya Uygulamalar için OAuth 2.0 Kullanma.
Varlıkları güncelleme
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 = '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); }
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ına örnek olarak artımlı güncellemeler, tam feed güncellemeleri ve ve API çağrısındaki içerik üst düzeydedir:
| Senaryo | Güncellenecek öğe | Açıklama ve efektler |
|---|---|---|
| Bir hizmeti devre dışı bırakma | Service |
Öngörülemeyen bir nedenle bir hizmeti devre dışı bırakmanız gerekiyor. Artımlı güncellemeler: Tam feed'ler: Öğeyi tam feed'lerden güncellediğinizden emin olun.
|
| Belirli bir ürün stokta yok | MenuItemOffer |
Artımlı güncellemeler: Kapsamlı MenuItemOffer öğesini gönderin
belirtilen için inventoryLevel değerine sahip varlık
MenuItem ve diğer tüm verilerde değişiklik yapılmadı. |
| Menü öğesi fiyat değişikliği | MenuItemOffer |
Artımlı güncellemeler: Kapsamlı MenuItemOffer öğesini gönderin
belirtilen tarih için güncellenmiş fiyata ayarlanmış price olan öğe
MenuItem ve diğer tüm verilerde değişiklik yapılmadı. |
|
Yeni üst düzey varlık ekleyin Yalnızca |
Menu, Restaurant Service |
Örneğin, bir restorana yeni bir menü eklemeniz gerekiyor. Tam feed'ler: Varlığı veri feed'lerinize ekleyin ve toplu beslemeyi bekleyin. |
|
Üst düzey öğeyi kalıcı olarak sil Yalnızca |
Menu, Restaurant Service |
Artımlı güncellemeler: açıkça silme. Tam feed'ler: Google Ads'e aktarmadan önce öğeyi tam feed'lerden kaldırdığınızdan emin olun. getirmez, aksi takdirde varlık yeniden eklenir. |
Belirli bir Service için yeni bir teslimat bölgesi ekleyin |
ServiceArea |
Ek feed'ler: Söz konusu ServiceArea öğesini, tüm özellikleriyle birlikte gönderin.
yeni teslimat alanıyla, tam feed'lerde olduğu gibi, olduğu gibi
polygon, geoRadius veya postalCode içinde belirtilir. |
Service konumunda teslimatın tahmini varış zamanını güncelleyin |
ServiceHours |
Ek feed'ler: ServiceHours öğesini
leadTimeMin değerinin güncellenmesi hariç feed'ler
buna göre hazırlar. |
Service cinsinden teslimat fiyatlarını güncelleyin |
Fee |
Ek feed'ler: Tam yayını Fee şununla gönderin:
price güncellendi. |
Service bölgesindeki teslimat veya paket servisi saatlerini güncelleyin |
ServiceHours |
Ek feed'ler: ServiceHours öğesini
opens ve closes özellikleri hariç olmak üzere feed'ler güncellendiğinde
buna göre hazırlar. |
Service (min. sipariş tutarını değiştir) |
Fee |
Ek feed'ler: Tam Fee değerini şununla gönder:
minPrice
güncellendi |
MenuItem öğesini kalıcı olarak silme |
Menu |
Ek feed'ler: MenuItem öğesini
ancak parentMenuSectionId boş bırakılmış.
|
Toplu işler ve artımlı güncellemeler için işleme süresiyle ilgili hizmet düzeyi hedefi (SLO)
Bir toplu taşıma işlemiyle güncellenen veya silinen bir varlık, 2 gün içinde işlenir. saatin en iyi şekilde güncellenmesi, ancak artımlı güncelleme ile güncellenen bir öğe işlenir. 5 dakika sürecek. Eski bir varlık 7 gün sonra silinir.
Google'a aşağıdakilerden birini 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.