v1 ek envanter güncellemeleri

Bu bölümde, feed'lerinizin zamana duyarlı güncellemelerini Google'a nasıl gönderebileceğiniz açıklanmaktadır. Artımlı Güncellemeler API'si, feed'lerinizdeki varlıkları neredeyse gerçek zamanlı olarak güncellemenizi ve silmenizi sağlar.

Bu işlev öncelikle acil durum kapatmaları gibi öngöremediğiniz güncellemelere yöneliktir. Kural olarak, Artımlı Güncellemeler API'si aracılığıyla gönderilen herhangi bir değişikliğin bir haftadan uzun süre içinde yayınlanması gerekir. Değişikliğinizin hemen yansıtılması gerekmiyorsa bunun yerine toplu güncelleme kullanabilirsiniz. Artımlı güncellemeler beş dakikadan fazla sürede işlenmez.

Kurulum

Artımlı güncellemeleri uygulamak için aşağıdakileri yapın:

1. Proje oluşturmak için Proje oluşturma ve ayarlama başlıklı makalede verilen adımları uygulayın.
2. Hizmet hesabı oluşturmak için Hizmet hesabı oluşturma sayfasında özetlenen adımları uygulayın. Hizmet hesabı için "Düzenleyici" rolü eklemek üzere projenin "Sahibi" olmanız gerektiğini unutmayın.
3. (İsteğe bağlı olsa da önerilir) API'yi çağırırken OAuth 2.0 kullanımını 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, jeton takaslarını Google API'lerine Erişmek için OAuth 2.0'ı Kullanma bölümünde açıklandığı şekilde manuel olarak işlemeniz gerekir.

Uç nokta

Google'ı bir güncelleme hakkında bilgilendirmek için Artımlı Güncellemeler API'sine bir HTTP POST isteği gönderin ve güncellemeler ve eklemeler yükünü ekleyin. Kullandığınız envanter şeması, hangi uç noktaya istekte bulunacağınızı belirler:

https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID:push

https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/ENTITY_ID:push

Bir varlığı kaldırmak için aşağıdaki uç noktaya, kullandığınız envanter şemasına karşılık gelen 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

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'inizde güncellemek istediğiniz nesnenin varlık türü (@type özelliği).
• ENTITY_ID: Yüke dahil olan tüzel kişinin kimliği. Varlık kimliğinizi URL olarak kodlamayı unutmayın.
• DELETE_TIME (yalnızca uç noktayı sil): Varlıkların sistemlerinizde silindiği zamanı belirtmek için kullanılan isteğe bağlı alandır (varsayılan olarak istek alındığında bu gerçekleşir). Zaman değeri gelecekte olmamalıdır. Varlıkları artımlı arama üzerinden gönderirken entity versioning, silme çağrısı durumunda delete_time alanını da kullanır. Bu değeri yyyy-mm-ddTHH:mm:ssZ olarak biçimlendir

Örneğin, v2 envanter şemasını kullanan "delivery-provider-id" kimliğine sahip bir projeniz var. Restoranda "MenüBölümü" restoran türü ve varlık menüsü "menuSection_122" kullanarak restoranda değişiklik yapmak istiyorsunuz. Verilerinizde yapılan güncellemeler için uç nokta aşağıdaki gibi olur:

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ündeki talimatları uygulayın ancak /v2/apps/ yerine /v2/sandbox/apps/ için istekte bulunun. Örneğin, v2 envanter şeması için korumalı alan silme isteği aşağıdaki şekilde yapılandırılmıştı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 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ünün yanı sıra istek parametrelerini de içermelidir.

JSON dosyası, aşağıdaki farklılıklarla birlikte toplu özet akışında olduğu gibi görünmelidir:

• Yükün boyutu 5 MB'tan büyük olmamalıdır. Toplu feed'lere benzer şekilde, daha fazla veri sığdırmak için boşlukları kaldırmanızı öneririz.
• Zarf şu şekildedir:

{
  "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 öğe dize olarak serileştirilmiş. JSON-LD varlığı data alanına dize olarak geçirilmelidir.
• 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 almasıdır. Varlıkları artımlı istek üzerinden gönderirken entity sürüm oluşturma, ekleme/güncelleme isteği durumunda update_time alanını da kullanır.

Varlık güncelleme

1. Örnek: Bir restoranı güncelleme

Bir restoranın telefon numarasını acil bir şekilde güncellemeniz gerektiğini varsayalım. Güncellemeniz tüm restoran için JSON içeriyor.

Aşağıdaki gibi görünen bir toplu feed'i değerlendirin:

{
  "@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
}

Sonra, HTTP POST'u 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ın güncellenmesi

Bir menü öğesinin fiyatını değiştirmeniz gerektiğini varsayalım. 1. Örnek'te olduğu gibi, güncellemenizin üst düzey varlığın tamamı (menü) için JSON içermesi gerekir. Feed, v1 envanter şemasını kullanır.

Aşağıdaki gibi görünen bir toplu feed'i değerlendirin:

{
  "@type": "MenuItemOffer",
  "@id": "menuitemoffer6680262",
  "sku": "offer-cola",
  "menuItemId": "menuitem896532",
  "price": 3.00,
  "priceCurrency": "USD"
}

Sonra, POST yoluyla artımlı güncellemeniz şöyle 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üncellemelerini kullanmaktan kaçının. Bunun yerine, toplu feed sürecini v2 envanter şemasında açıklandığı şekilde kullanın.

Varlık kaldırma

Üst düzey varlıkları kaldırmak için hafif olarak değiştirilmiş bir uç nokta ve istekte HTTP POST yerine HTTP DELETE kullanın.

Üst düzey varlık içindeki bir alt varlığı (örneğin, menüdeki menü öğesi) kaldırmak için HTTP SİLME'yi 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ığın güncellemesi olarak değerlendirin.

1. Örnek: Üst düzey bir varlığı silme

v1 envanter şemasını kullanan bir feed'deki bir restoranı silmek istediğiniz bir durumu düşünün. Ayrıca hizmetlerini ve menülerini de silmeniz gerekir.

`https://www.provider.com/restoran/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

Bir restoran varlığı için şu kimlikle örnek bir uç nokta: https://www.provider.com/restoran/nr"

DELETE v2/apps/delivery-provider-id/entities/https%3A%2F%2Fwww.provider.com%2Frestaurant%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com

Aşağıdakileri içeren bir varlık varlığı için örnek uç nokta: https://www.provider.com/restoran/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 varlığı üst düzey bir varlık içinden kaldırmak için bu alt varlığın karşılık gelen alandan kaldırıldığı üst düzey varlığı 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ırılan 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 anlamına gelmez, yalnızca API çağrısının yapıldığını gösterir. Başarılı aramalar, boş bir yanıt gövdesiyle birlikte bir HTTP yanıt kodu 200 alır:

{}

Başarısızlıklar için HTTP yanıt kodu 200 olmaz. Yanıt gövdesi, sorunun ne olduğunu gösterir.

Örneğin, kullanıcı zarftaki "vertical"quot 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, çeşitli dillerde Artımlı Güncellemeler API'sinin nasıl kullanılacağına dair bazı örnekler verilmiştir. Bu örnekler Google Auth Kitaplıklarını kullanır ve v1 envanter şemasını kullanarak bir feed kabul eder. Alternatif çözümler için Sunucudan Sunucuya Uygulamalarda OAuth 2.0'ı Kullanma başlıklı makaleye bakın.

Varlıkları güncelleme

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)

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 '{}'

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

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)

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 '{}'

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ında üst düzey içerik örnekleridir:

Toplu işler ve artımlı güncellemeler için işleme süresinde Qwiklab

Toplu veya artımlı güncelleme aracılığıyla eklenen bir varlık 1-2 gün içinde işlenir. Bir toplu işlem aracılığıyla güncellenen veya silinen varlık 2 saat içinde, artımlı güncelleme aracılığıyla güncellenen öğe ise 5 dakika içinde işlenir. Eski bir varlık 7 gün içinde silinir.

Google’a şunları gönderebilirsiniz:

• Envanterinizi güncel tutmak için günde birden fazla toplu iş olması VEYA
• Envanterinizi güncel tutmak için günde bir toplu iş ve Artımlı API'ler.