本頁面由 Cloud Translation API 翻譯而成。

v1 漸進式商品目錄更新

本節說明如何將具有時效性的動態饋給更新傳送給 Google。您可以運用 Incremental Updates API 即時更新及刪除動態饋給中的實體。

這項功能主要用於無法預見的更新，例如緊急關閉。一般而言，透過 Incremental Updates API 提交的變更都應該在一週內生效。如果您的變更不需要立即反映，可以改用批次更新。增量更新可在五分鐘內處理完畢。

設定

如要實作漸進式更新，請執行下列操作：

按照「建立並設定專案」一文提供的步驟操作，建立專案。
按照設定服務帳戶一文所述的步驟建立服務帳戶。請注意，您必須是專案的「擁有者」，才能為服務帳戶新增「編輯者」角色
(建議選用) 安裝 Google 用戶端程式庫，安裝時應以您選擇的語言安裝，以便呼叫 API 時使用 OAuth 2.0。下列程式碼範例使用的是這些程式庫。否則，您必須按照「使用 OAuth 2.0 存取 Google API」一文中的說明，手動處理權杖交換。

端點

如要將更新通知 Google，請向 Incremental Updates API 發出 HTTP POST 要求，並加入更新和新增項目的酬載。您使用的廣告空間結構定義會決定您要向哪個端點發出要求：

v2 廣告空間

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 要求，該端點會對應您使用的庫存結構定義：

v2 廣告空間

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 為「Deliver-provider-id」，使用 v2 廣告空間結構定義。您想要變更餐廳實體類型為「MenuSection」且實體 ID 為「menuSection_122」的餐廳。更新資料的端點如下：

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/。舉例來說，第 2 版廣告空間結構定義的沙箱刪除要求結構如下：

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

更新與新增內容

每日批次動態饋給也應包含透過此 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：更新餐廳

假設您急需更新餐廳的電話號碼，您的更新包含整個餐廳的 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 所示，您的更新必須包含整個頂層實體 (選單) 的 JSON，且動態饋給會使用 v1 庫存結構定義。

請考慮採用如下所示的批次動態饋給：

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

新增實體

如要新增實體，請避免使用商品目錄更新功能。請改為按照 v2 庫存結構定義所述，使用批次動態饋給程序。

移除實體

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

請勿使用 HTTP DELETE 來移除頂層實體 (例如選單項目) 中的子實體。請改為將子實體移除視為從相關清單或參數中移除的頂層實體更新。

範例 1：刪除頂層實體

假設您想在使用 v1 庫存結構定義的動態饋給中刪除餐廳。此外，也必須刪除相關服務和選單。

選單實體 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 為「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：移除子實體

如要從頂層實體中移除子實體，您必須傳送從對應欄位中移除子實體的頂層實體。以下範例假設動態饋給使用 v1 庫存結構定義。

舉例來說，如要移除服務範圍，請更新服務，並將服務範圍從 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，而回應主體會指出發生錯誤的原因。

舉例來說，如果使用者將信封中的「垂直」值設為 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 驗證程式庫，並假設使用 v1 庫存結構定義的動態饋給。如需替代解決方案，請參閱「針對伺服器對伺服器應用程式使用 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`	出於未預期的原因，您必須停用服務。增量更新：將有 `@type` 的問題 `Service` 實體傳送給 `DisabledService`，但其他屬性保持不變。完整動態饋給：請務必在 Google 下次擷取實體前，將完整動態饋給中的實體更新為 `@type` 設為 `DisabledService`，否則實體會重新啟用。
特定商品缺貨	`Menu`	增量更新：針對指定的 `MenuItem`，傳送 `offer.inventoryLevel` 設為 0 的封裝 `Menu` 實體，以及所有其他資料維持不變。
選單項目價格異動	`Menu`	增量更新：傳送含有 `offer.price` 的封裝 `Menu` 實體，並將 `offer.price` 設為指定 `MenuItem` 的更新價格，所有其他資料則維持不變。
新增頂層實體僅適用於 `Menu`、`Restaurant` 和 `Service` 類型的實體。	`Menu`、`Restaurant`、`Service`	舉例來說，您必須在餐廳中新增菜單。增量更新：傳送新的菜單實體以及餐廳實體，其中的 `hasMenu` 欄位也會隨之更新。
永久刪除頂層實體僅適用於 `Menu`、`Restaurant` 和 `Service` 類型的實體。	`Menu`、`Restaurant`、`Service`	增量更新：傳送明確刪除。完整動態饋給：請務必在 Google 下次擷取實體前，將實體從完整動態饋給中移除，否則會重新加入實體。
新增特定`Service`的寄送區域	`Service`	增量動態饋給：傳送有問題的 `Service` 實體並完整呈現所有欄位，就像您平常在完整動態饋給中一樣，並在 `Service` 的 `areaServed` 中指定新的運送區域。
更新 `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，讓庫存保持在最新狀態。