v2 廣告空間增量更新

本節說明如何將商品目錄實體的時效性更新傳送給 Google。Incremental Update API 可讓您近乎即時地推送更新及刪除沙箱或實際工作環境中的實體。

這項功能主要適用於無法預見的更新 (例如緊急關閉通知)。根據規則，凡是透過 Increment Update API 提交的變更，都應該在一小時內生效。如果不需要立即反映變更，您可以改用批次擷取。更新作業會在五分鐘內完成。

必要條件

實作漸進式更新之前，請確認以下項目：

  1. 系統會透過建立動作專案的編輯者角色來建立服務帳戶。詳情請參閱建立及設定專案。
  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 為「quot;delivery-provider-id&quot」的專案中的實體，端點會如下所示：

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

舉例來說，如要從「quot;delivery-provider-id"」專案刪除 ID 為「quoSection;menuSection"」的實體，您應發出 HTTP DELETE API 呼叫來：

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

沙箱環境

如要在沙箱廣告空間中使用 Incremental Update 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 應與批次動態饋給中的結果相同，但有以下差異：

  • 酬載主體的大小不得超過 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，而動態饋給會使用 v1 庫存結構定義。

批次批次動態饋給應如下所示：

{
  "@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」 ID 的選單實體範例端點：

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

程式碼範例

以下提供一些範例，說明如何以不同語言使用 Incremental Update 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 = '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實體，將isDisabled屬性設為true，其他屬性則維持不變。

完整動態饋給：在 Google 下次擷取前，請務必更新完整動態饋給中的實體，並將 isDisabled 設為 true，否則實體就會重新啟用。
特定商品缺貨中 MenuItemOffer 遞增更新：針對指定的 MenuItem 傳送封裝為 inventoryLevel 的封裝實體 MenuItemOffer，且其他資料維持不變。
菜單商品價格異動 MenuItemOffer 漸進式更新：傳送 price 實體封裝，並將 price 實體設為給定 MenuItem 的更新價格，所有其他資料則維持不變。

新增頂層實體

僅適用於 Menu、Restaurant 和 Service 類型實體。

 Service 年取得MenuRestaurant學位

舉例來說，你必須在餐廳中新增菜單。

完整動態饋給：在資料動態饋給中加入實體，然後等待批次擷取。

永久刪除頂層實體

僅適用於 Menu、Restaurant 和 Service 類型實體。

 Service 年取得MenuRestaurant學位

漸進式更新：傳送明確刪除。

完整動態饋給：在 Google 下次擷取前，請先從完整動態饋給中移除實體，否則這個實體就會重新加入。
在特定 Service 中新增運送區域 ServiceArea 漸進式動態饋給：傳送有爭議的 ServiceArea 實體，確保所有欄位都完整不變，就像一般在完整動態饋給中一樣，並以 polygon、geoRadius 或 postalCode 指定新交付區域。
更新Service的預估送達時間 ServiceHours 漸進式動態饋給：傳送 ServiceHours 與動態饋給中相同，但其 leadTimeMin 會隨之更新。
更新Service的價格 Fee 漸進式動態饋給：透過 price 傳送完整傳送 Fee。
更新「Service」的外送或外帶時段 ServiceHours 漸進式動態饋給：傳送 ServiceHours 與動態饋給中相同，但其 opens 和 closes 屬性會隨之更新。
Service (變更最低訂單金額) Fee 漸進式動態饋給：傳送完整的 Fee 並更新 minPrice
永久刪除 MenuItem Menu 漸進式動態饋給：傳送MenuItem與動態饋給相同，但 parentMenuSectionId空白。

批次工作處理時間和漸進式更新作業的服務水準協議

以批次方式更新或刪除透過實體更新的實體，會在 2 小時內處理完畢，而透過漸進式更新更新的實體則需在 5 分鐘內處理。過時實體會在 7 天後刪除。

你可以傳送下列資料給 Google：

  • 每天可執行多項批次工作，確保商品目錄符合現況，或是
  • 每天一次一個批次工作，並搭配漸進式 API 讓廣告空間保持最新狀態。