Bu bölümde, feed'lerinizin zamana duyarlı güncellemelerini Google'a dokunun. Artımlı Güncellemeler API'si, neredeyse gerçek zamanlı olarak yayınlıyorsunuz.
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üncellemeler API'si en geç bir hafta. Değişikliğinizin hemen uygulanması gerekmiyorsa, bunun yerine toplu güncelleme yapabilirsiniz. Artımlı güncellemeler en fazla beş saniyede işlenir. dakika.
Kurulum
Artımlı güncellemeleri uygulamak için aşağıdakileri yapın:
- Proje oluşturma ve ayarlama başlıklı makalede belirtilen adımları uygulayarak bahsedeceğiz.
- Hizmet hesabı oluşturma başlıklı makalede açıklanan adımları uygulayın hizmet hesabı oluşturun. "Sahip" olmanız gerektiğini unutmayın "Düzenleyici" ekleyerek rol ve sorumlulukları
- (İ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ç nokta
Google'ı bir güncelleme konusunda bilgilendirmek için artımlı Güncellemeler API'si ve güncelleme ile ekleme yükünü içerir. Kullandığınız envanter şeması, istekte bulunacağınız uç noktayı 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 aşağıdaki uç noktaya HTTP DELETE isteği gönderin. ilgili envanter şemasına karşılık gelir:
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ğıdaki değişiklikleri yapın:
- PROJECT_ID: Projenizle ilişkili Google Cloud proje kimliği Proje oluşturma ve ayarlama bölümünde oluşturulur.
- TYPE (yalnızca v2 envanter şeması): Varlık türü (
@type
özelliği) veri feed'inizde güncellemek istediğiniz nesnenin. - ENTITY_ID: Yüke dahil edilen 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_time
alanını da kullanır. Bunu biçimlendiryyyy-mm-ddTHH:mm:ssZ
olarak değer
Örneğin, kimliği "delivery-provider-id" olan bir projeniz var. Google Analytics 4'te v2 envanter şeması. Restoranda şununla değişiklik yapmak istiyorsunuz: "MenüBölümü" olan restoran tüzel kişiliği ve "menuSection_122" varlık kimliği. Verilerinizde güncelleme yapılacak son nokta şudur:
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 verilen talimatları uygulayın ancak
/v2/apps/
yerine /v2/sandbox/apps/
isteğinde bulun. Örneğin,
v2 envanter şeması için 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'ye gidin. Aksi takdirde, toplu güncellemeleriniz artımlı değişikliklerinizin üzerine yazılır.
Yük
Her POST isteği, JSON ile birlikte istek parametrelerini içermelidir envanter şeması.
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:
{ "entity": { "data":"ENTITY_DATA", "vertical":"FOODORDERING" }, "update_time":"UPDATE_TIMESTAMP" }
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ığı,
data
alanı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_time
alanına girilen değeri gösterir.
Varlık güncelleme
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/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ü 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/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ı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.
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, ilgili liste veya parametredir.
1. Örnek: Üst düzey bir öğeyi silme
Şu durumu düşünün: v1 envanter şeması. Ayrıca hizmetlerini ve menülerini de silmeniz gerekir.
Kimliği olan bir menü öğesi için örnek uç nokta "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
Kimliği olan bir restoran varlığı için örnek uç nokta "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
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/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 öğeyi üst düzey bir varlıktan kaldırmak için söz konusu öğenin üst düzeyindeki alt varlığı ilgili alandan kaldırmış olmanız gerekir. Aşağıdakiler feed'in v1 envanter şemasını kullandığını varsayar.
Örneğin, bir hizmet bölgesini kaldırmak için hizmeti hizmet bölgesiyle güncelleyin.
areaServed
listesinden kaldırıldı.
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 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üncellemeler API'sinin çeşitli cihazlarda nasıl kullanılacağına 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 = '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ına örnek olarak artımlı güncellemeler, tam feed güncellemeleri ve ve API çağrısındaki içerik üst düzeydedir:
Senaryo | Üst düzey varlık | Açıklama ve efektler |
---|---|---|
Bir hizmeti devre dışı bırakma | DisabledService |
Ö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 | Menu |
Artımlı güncellemeler: Kapsamlı Menu öğesini gönderin
belirtilen için offer.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 | Menu |
Artımlı güncellemeler: Kapsamlı Menu öğesini gönderin
belirtilen tarih için güncellenmiş fiyata ayarlanmış offer.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. Ek güncellemeler: Restoranla birlikte yeni menü öğesini gönderin
|
Ü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 |
Service |
Ek feed'ler: Söz konusu Service öğesini, tüm özellikleriyle birlikte gönderin.
yeni teslimat alanıyla, tam feed'lerde olduğu gibi, olduğu gibi
Service içinde areaServed içinde belirtilir. |
Service konumunda teslimatın tahmini varış zamanını güncelleyin |
Service |
Ek feed'ler: Service öğesini
hoursAvailable.deliveryHours değerinin güncellenmesi hariç feed'ler
buna göre hazırlar. |
Service cinsinden teslimat fiyatlarını güncelleyin |
Service |
Ek feed'ler: Tam Service değerini şununla gönder:
offers.priceSpecification.price güncellendi. |
Service bölgesindeki teslimat veya paket servisi saatlerini güncelleyin |
Service |
Ek feed'ler: Service öğesini
hoursAvailable değerinin güncellenmesi hariç feed'ler
buna göre hazırlar. |
Service (min. sipariş tutarını değiştir) |
Service |
Ek feed'ler: Tam Service değerini şununla gönder:
Service.offers.priceSpecification.eligibleTransactionVolume
güncellendi |
MenuItem adlı kişiyi kalıcı olarak sil |
Menu |
Ek feed'ler: Menu öğesini
feed'ler, ancak bu MenuItem
hasMenuItems listesi. |
Toplu işler ve artımlı güncellemeler için işleme süresiyle ilgili hizmet düzeyi hedefi (SLO)
Toplu veya artımlı güncelleme ile eklenen bir öğe şurada işlenir: 1-2 gün. Bir toplu taşıma işlemiyle güncellenen veya silinen bir varlık, 2 saniye içinde işlenir. saat cinsinden, artımlı güncellemeyle güncellenen bir öğe ise 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.