v2 累加型商品目錄更新

本節說明如何將庫存實體的時間敏感更新內容傳送給 Google。透過增量更新 API,您可以在沙箱或實際工作環境的廣告空間中,以近乎即時的方式推送更新及刪除實體。

這項功能主要用於處理你無法預測的更新內容,例如緊急關閉。一般來說,透過增量更新 API 提交的任何變更,都必須在 1 小時內生效。如果變更不需要立即反映,您可以改用批次擷取。增量更新作業最多需要五分鐘才能處理完畢。

必要條件

您必須先實作以下項目,才能導入增量更新:

  1. 系統會為 Actions 專案建立具有編輯者角色的服務帳戶。詳情請參閱「建立及設定專案」一文。
  2. 主機或沙箱資料動態饋給會代管及擷取。詳情請參閱批次攝入
  3. (選用,但建議安裝) 以您選擇的語言安裝 Google 用戶端程式庫,方便在呼叫 API 時使用 OAuth 2.0。下方程式碼範例使用這些程式庫。否則,您必須手動處理符記交換,如「使用 OAuth 2.0 存取 Google API」一文所述。

端點

在下列要求中,請替換以下內容:

  • PROJECT_ID:與您在「建立及設定專案」中建立的專案相關聯的 Google Cloud 專案 ID。
  • TYPE:您要更新的資料動態饋給中物件的實體類型 (@type 屬性)。
  • ENTITY_ID (僅限刪除端點):要刪除的實體 ID。請務必將實體 ID 編碼為網址格式。
  • DELETE_TIME (僅限刪除端點):選用欄位,用於表示實體在系統中刪除的時間 (預設為收到要求時)。時間值不得在未來,透過增量呼叫傳送實體時,實體版本控制也會在刪除呼叫的情況下使用 delete_time 欄位。將這個值格式化為 yyyy-mm-ddTHH:mm:ssZ

更新端點

如要修改實體,請向下列端點發出 HTTP POST 要求,並附上更新和新增項目的酬載。您可以在單一 API 呼叫中更新最多 1,000 個實體。

https://actions.googleapis.com/v2/apps/PROJECT_ID/entities:batchPush

舉例來說,如果您想更新 ID 為「delivery-provider-id」的專案中實體,端點會是以下內容:

https://actions.googleapis.com/v2/apps/delivery-provider-id/entities:batchpush

刪除端點

如要刪除商品目錄中的實體,請向下列端點發出 HTTP DELETE 要求。

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

舉例來說,如要從「delivery-provider-id」專案中刪除 ID 為「menuSection_122」的「MenuSection」實體,您可以呼叫以下 HTTP DELETE API:

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

沙箱環境

如要在沙箱廣告空間中使用增量更新 API,請按照上述「端點」一節的說明操作,但請向 /v2/sandbox/apps/ 提出要求,而非 /v2/apps/

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

更新實體

每個 POST 要求都必須包含要求參數,以及含有廣告空間結構定義中列出的任何實體類型的結構化資料的 JSON 酬載。

更新酬載

JSON 應與批次動態饋給中的 JSON 相同,但有以下差異:

  • 酬載內容不得超過 5 MB。與批次動態饋給類似,建議您為塞入更多資料而移除空格。
  • 信封如下:
{
  "requests": [
    {
      "entity": {
        "data":"ENTITY_DATA",
        "name": "apps/project_id>/entities/type/entity_id"
      },
      "update_time":"UPDATE_TIMESTAMP"
    },
  ],
  "vertical": "FOODORDERING"
}

在上述酬載中,請替換下列項目:

  • ENTITY_DATA:以字串序列化的 JSON 格式實體。JSON-LD 實體必須以字串形式傳遞至 data 欄位。
  • UPDATE_TIMESTAMP (選用):實體在系統中更新的時間戳記。時間值不得在未來,預設時間戳記是 Google 收到要求的時間。透過增量要求傳送實體時,實體版本控制也會在新增/更新要求的情況下使用 update_time 欄位。

範例

範例 1:更新餐廳

假設你需要緊急更新餐廳的電話號碼,更新內容包含整個餐廳的 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/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:更新多間餐廳

如要在單一 API 呼叫中更新兩個餐廳實體,HTTP POST 要求會如下所示:

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

假設您需要變更菜單項目的價格。如同範例 1 所示,更新內容必須包含整個頂層實體 (選單) 的 JSON,且動態饋給使用第 1 版廣告空間結構定義。

請參考以下批次動態饋給:

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

透過 POST 進行的增量更新會如下所示:

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

新增實體

如要新增實體,請避免使用商品目錄更新功能。請改用批次動態饋給程序,如第 2 版廣告空間結構定義所述。

移除實體

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

刪除頂層實體

假設您想刪除動態中的餐廳,您也必須刪除相關服務和選單。

菜單實體 ID 為「provider/restaurant/menu/nr」的範例端點:

DELETE v2/apps/delivery-provider-id/entities/menu/provider%2Frestaurant%2Fmenu%2Fnr?entity.vertical=FOODORDERING
Host: actions.googleapis.com

餐廳實體的 ID 為「https://www.provider.com/restaurant/nr」的端點範例:

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

服務實體 ID 為「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
}

移除子實體

請勿使用 HTTP DELETE 移除頂層實體中的子實體,例如選單中的選單項目。請改為將子實體移除作業視為頂層實體的更新作業,在該作業中,子實體會從相關清單或 reverseReference 中移除。

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

程式碼範例

以下是一些範例,說明如何在各種語言中使用增量更新 API。這些範例會使用 Google 驗證程式庫,並假設動態饋給使用第 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 = '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

這個程式碼使用 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 = '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

此程式碼使用 Java 專用的 Google 授權程式庫

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

移除實體

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 呼叫中高層級內容的範例:

情境 要更新的實體 說明和影響
停用服務 Service

您需要基於不可預測的原因停用服務。

逐步更新:將問題中的 Service 實體更新為 true,但其他屬性保持不變。isDisabled

完整動態饋給:請務必在 Google 下次擷取前,從完整動態饋給更新實體,將 isDisabled 設為 true,否則系統會重新啟用實體。

特定商品缺貨 MenuItemOffer 增量更新:傳送封裝的 MenuItemOffer 實體,其中 inventoryLevel 已設為給定 MenuItem 的 0,所有其他資料均保持不變。
菜單項目價格異動 MenuItemOffer 增量更新:傳送封裝的 MenuItemOffer 實體,其中 price 設為指定 MenuItem 的更新價格,所有其他資料均保持不變。

新增頂層實體

僅適用於 MenuRestaurantService 類型的實體。

MenuRestaurantService

例如,你需要為餐廳新增菜單。

完整動態饋給:在資料動態饋給中新增實體,並等待批次攝入。

永久刪除頂層實體

僅適用於 MenuRestaurantService 類型的實體。

MenuRestaurantService

分批更新:傳送明確刪除

完整動態饋給:請務必在 Google 下次擷取前,從完整動態饋給中移除實體,否則系統會重新加入實體。

在特定 Service 中新增運送區域 ServiceArea 動態饋給:傳送相關 ServiceArea 實體,並保留所有欄位,就像在完整動態饋給中一樣,並在 polygongeoRadiuspostalCode 中指定新的刊登地區。
更新 Service 的預估送達時間 ServiceHours 漸進式動態饋給:傳送的 ServiceHours 與動態饋給中的相同,但其 leadTimeMin 會依據情況更新。
更新 Service 中的運送價格 Fee 增量動態饋給:傳送已更新的 price 和完整的 Fee
Service 中更新外送或外帶營業時間 ServiceHours 漸進式動態饋給:傳送的 ServiceHours 與動態饋給中的相同,但其 openscloses 屬性會依據情況更新。
Service (變更最低訂單金額) Fee 動態饋給增量資料:傳送已更新的 minPrice 和完整 Fee
永久刪除 MenuItem Menu 漸進式動態饋給:傳送的 MenuItem 與動態饋給相同,但 parentMenuSectionId 為空白。

批次工作和增量更新的處理時間服務等級目標

透過批次更新或刪除實體時,系統會在 2 小時內以盡力模式處理,而透過增量更新更新實體時,系統會在 5 分鐘內處理。過時實體會在 7 天內刪除。

您可以傳送下列資料給 Google:

  • 每天執行多個批次工作,以便隨時更新商品目錄,或
  • 每天執行一次批次作業和增量 API,確保商品目錄保持最新狀態。