v1 漸進式商品目錄更新

本節說明如何將具有時效性的動態饋給更新傳送給 Google。Incremental Updates API 可讓您更新及刪除 以近乎即時的方式處理動態饋給

這項功能主要是供您無法預見的更新 例如緊急關閉。通常透過 漸進式更新 API 應在以下時間以內推出: 1 週。如果不需要立即反映變更,您可以 執行批次更新漸進式更新最多處理五項 分鐘。

設定

如要實作漸進式更新,請按照下列步驟操作:

  1. 按照「建立及設定專案」一文中所述的步驟操作, 建立專案。
  2. 按照「設定服務帳戶」所述的步驟操作 來建立服務帳戶請注意,你必須是「擁有者」的 來新增「編輯者」服務帳戶的角色
  3. (建議選用) 安裝 Google 用戶端程式庫 並在呼叫 也能使用 Google Cloud CLI 或 Compute Engine API以下提供的程式碼範例使用了這些程式庫。否則, 必須手動處理權杖交換,如使用 OAuth 2.0 存取 Google API 一文所述。

端點

如要通知 Google 有更新,請向遞增單位發出 HTTP POST 要求 更新 API,並加入更新與新增項目的酬載。 您使用的廣告空間架構會決定要向哪個端點發出要求:

第 2 版廣告空間

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

v1 廣告空間

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

如要移除實體,請向下列端點發出 HTTP DELETE 要求: 對應的廣告空間架構:

第 2 版廣告空間

https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME

v1 廣告空間

https://actions.googleapis.com/v2/apps/PROJECT_ID/entities/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME

在上述要求中,替換以下內容:

  • PROJECT_ID:與您專案相關聯的 Google Cloud 專案 ID 在建立及設定專案中建立的專案。
  • TYPE (僅限 v2 個商品目錄架構):實體類型 (@type 資源) 該物件的所有屬性。
  • ENTITY_ID:酬載中包含的實體 ID。請務必 將實體 ID 進行網址編碼。
  • DELETE_TIME (僅限刪除端點):用來表示 實體在您系統中刪除的時間 (預設為要求 )。時間值不得為未來的時間。傳送實體時 透過漸進式呼叫實體版本管理 如果是刪除呼叫,也會使用 delete_time 欄位。格式化 值是 yyyy-mm-ddTHH:mm:ssZ

舉例來說,您有一個 ID 為「delivery-provider-id」的專案使用 第 2 版商品目錄架構你想用 餐廳實體類型「MenuSection」和「menuSection_122」的實體 ID 更新資料的端點如下:

https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122:push

如要移除這個實體,您必須進行以下 HTTP DELETE API 呼叫:

https://actions.googleapis.com/v2/apps/delivery-provider-id/entities/MenuSection/menuSection_122?entity.vertical=FOODORDERING

沙箱請求

針對沙箱要求,請遵循上方 Endpoint 中的指示操作,但 向 /v2/sandbox/apps/ 發出要求,而非 /v2/apps/。舉例來說, v2 商品目錄結構定義的沙箱刪除請求結構如下:

https://actions.googleapis.com/v2/sandbox/apps/PROJECT_ID/entities/TYPE/ENTITY_ID?entity.vertical=FOODORDERING&delete_time=DELETE_TIME

更新與附加內容

每日批次動態饋給也必須包含透過這個表格提交的所有變更 也能使用 Google Cloud CLI 或 Compute Engine API否則,批次更新會覆寫增量變更。

酬載

每個 POST 要求都必須包含要求參數與 JSON 內含 廣告空間架構

JSON 顯示的內容應與批次動態饋給中的資訊相同, 下列差異:

  • 酬載主體的大小不得超過 5 MB。與批次作業類似 為了容納更多資料,建議您去除空白字元。
  • 信封如下所示:
{
  "entity": {
    "data":"ENTITY_DATA",
    "vertical":"FOODORDERING"
  },
  "update_time":"UPDATE_TIMESTAMP"
}

在上述酬載中,替換以下內容:

  • ENTITY_DATA:JSON 格式的實體,已序列化為字串。 JSON-LD 實體必須在 data 欄位中以字串的形式傳遞。
  • UPDATE_TIMESTAMP (選用):實體更新時間的時間戳記: 以及系統時間值不得為未來的時間。預設時間戳記處於 Google 收到要求後,透過 要求,實體版本管理也會使用 update_time 欄位。
,瞭解如何調查及移除這項存取權。

更新實體

範例 1:更新餐廳

假設您急需更新餐廳的電話號碼,您的 update 會包含整間餐廳的 JSON。

假設批次動態饋給如下所示:

{
  "@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 的漸進式更新會如下所示:

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:更新菜單品項價格

假設您需要變更選單項目的價格,如範例 1 所示,您的 update 必須包含整個頂層實體 (選單) 的 JSON,而 動態饋給會採用第 1 版商品目錄架構。

假設批次動態饋給如下所示:

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

那麼透過 POST 進行的漸進式更新會如下所示:

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"
  }
}
敬上

新增實體

如要新增實體,請避免使用商品目錄更新項目。建議改用批次動態饋給 第 2 版商品目錄架構中所述的程序。

移除實體

如要移除頂層實體,請使用稍微修改的端點。 並在要求中使用 HTTP DELETE,而不是 HTTP POST。

請勿使用 HTTP DELETE 來移除頂層實體中的子實體,例如: 選單項目您可以將移除子實體視為 更新至從 相關的清單或參數

範例 1:刪除頂層實體

假設在某項動態饋給中需要刪除餐廳,而該動態饋給使用 第 1 版商品目錄架構此外,你也必須刪除相關服務和選單。

選單實體 (ID 為) 的範例端點 "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

ID 為其他餐廳實體的端點範例 "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

ID 為 ID 的服務實體的端點範例 "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:移除子實體

如要從頂層實體中移除子實體,請傳送頂層實體 實體的子實體已從對應欄位中移除。下列 範例假設動態饋給使用第 1 版商品目錄結構定義。

舉例來說,如要移除服務範圍,請更新服務並加入服務範圍 已從「areaServed」清單中移除。

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 回應代碼

呼叫成功不代表動態饋給有效或正確,只表示 已進行 API 呼叫。成功的呼叫會收到 HTTP 回應代碼 200,以及 空白回應主體:

{}

如果失敗,HTTP 回應代碼不會是 200,而回應主體 代表出了問題

舉例來說,如果使用者將「vertical」設為輸入 FAKE_VERTICAL,您會收到以下訊息:

{
  "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\""
          }
        ]
      }
    ]
  }
}

程式碼範例

下方範例說明如何在各種應用程式中使用 Incremental Updates API 語言。這些範例使用 Google Auth 程式庫,並假設動態饋給為 第 1 版商品目錄架構如要瞭解替代解決方案,請參閱 針對伺服器對伺服器應用程式使用 OAuth 2.0

更新實體

Node.js

這個程式碼使用 Node.js 適用的 Google 驗證程式庫

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

這段程式碼使用 Python 適用的 Google 驗證程式庫

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

這個程式碼使用 Java 適用的 Google 驗證程式庫

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);
}

移除實體

Node.js

這個程式碼使用 Node.js 適用的 Google 驗證程式庫

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

這段程式碼使用 Python 適用的 Google 驗證程式庫

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

這個程式碼使用 Java 適用的 Google 驗證程式庫

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));
}

用途

以下列舉幾個使用漸進式更新、完整動態饋給更新、 和 API 呼叫中高階的內容:

情境 頂層實體 說明與效果
停用服務 DisabledService

您必須基於未預期的原因停用服務。

增量更新:在以下位置傳送 Service 實體: @type的問題已變更為 DisabledService,但其他屬性維持不變。

完整動態饋給:請務必更新完整動態饋給中的實體 必須將「@type」設為「DisabledService」,才能 下一次由 Google 擷取,否則系統將重新啟用該實體。

特定產品缺貨中 Menu 增量更新:傳送封裝的 Menu 就指定類別而言,offer.inventoryLevel 設為 0 的實體 MenuItem,所有其他資料則維持不變。
菜單品項價格異動 Menu 增量更新:傳送封裝的 Menu offer.price 設定為指定的更新價格 MenuItem,所有其他資料則維持不變。

新增頂層實體

僅適用於 Menu 類型的實體, RestaurantService

MenuRestaurantService

舉例來說,您需要為餐廳新增菜單,

增量更新:傳送新的菜單實體至餐廳 實體及其 hasMenu 欄位的內容也會隨之更新。

永久刪除頂層實體

僅適用於 Menu 類型的實體, RestaurantService

MenuRestaurantService

增量更新:傳送 「明確刪除」

完整動態饋給:請務必在 下一次 Google 擷取,否則會重新加入該實體。

新增特定Service的送貨區域 Service 漸進式動態饋給:傳送相關的 Service 實體和所有 欄位完整保留,就像您平常在完整動態饋給內一樣,並新增了運送區域 在 ServiceareaServed 內指定。
更新Service後的預計送達時間 Service 漸進式動態饋給:傳送與活動相同的 Service 動態饋給,但 hoursAvailable.deliveryHours 除外 。
更新Service的配送價格 Service 漸進式動態饋給:以下列方式傳送完整的「Service」: 已更新「offers.priceSpecification.price」。
更新Service的外送或外帶時段 Service 漸進式動態饋給:傳送與活動相同的 Service 動態饋給,但 hoursAvailable 除外 。
Service (變更最低訂單金額) Service 漸進式動態饋給:以下列方式傳送完整的「Service」: Service.offers.priceSpecification.eligibleTransactionVolume 已更新
永久刪除MenuItem Menu 漸進式動態饋給:傳送與活動相同的 Menu 但由於此MenuItem已從 hasMenuItems 清單。

批次工作和漸進式更新處理時間的服務等級目標

透過批次或漸進式更新新增的實體,會在以下位置進行處理: 1 到 2 天。透過批次更新或刪除的實體,系統會在第 2 個步驟中處理該實體 小時,透過增量更新對實體進行更新時 短短 5 分鐘內就能完成過時實體會在 7 天後刪除。

您可以向 Google 傳送以下資訊:

  • 每天執行多項批次工作,讓商品目錄資料保持在最新狀態。
  • 每天一項批次工作和漸進式 API,讓商品目錄資料保持最新狀態。