v1 增量商品目录更新

本部分介绍了如何向 Google 发送 Feed 的紧急更新。借助增量更新 API，您可以近乎实时地更新和删除 Feed 中的实体。

注意 ：除非您已获得豁免，否则必须将此功能添加到您的 Action 中。如果您不确定是否需要实施商品目录更新，请与您的 Google 顾问联系。

此功能主要用于您无法预见的更新，例如紧急关闭。通常，通过增量更新 API 提交的任何更改都必须在 1 周内生效。如果您不需要立即反映更改，可以改用批量更新。增量更新的处理时间不超过 5 分钟。

设置

如需实现增量更新，请执行以下操作：

1. 按照创建和设置项目中所述的步骤创建项目。
2. 按照设置服务账号中所述的步骤创建服务账号。请注意，您需要是项目的“Owner”（所有者），才能为服务账号添加“Editor”（编辑者）角色
3. （可选，但建议）安装您偏好的语言版本的 Google 客户端库，以便在调用 API 时使用 OAuth 2.0。以下代码示例使用这些库。否则，您需要手动处理令牌交换，如使用 OAuth 2.0 访问 Google API 中所述。

端点

如需通知 Google 有更新，请向增量更新 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 商品目录架构）：您要更新的数据 Feed 中对象的实体类型（@type 属性）。
• ENTITY_ID：载荷中包含的实体的 ID。请务必对实体 ID 进行网址编码。
• DELETE_TIME（仅限删除端点）：可选字段，用于指明实体在您的系统中被删除的时间（默认是收到请求的时间）。时间值不得是将来的时间。通过增量调用发送实体时，实体版本控制在删除调用的情况下也会使用 delete_time 字段。将此值格式化为 yyyy-mm-ddTHH:mm:ssZ

例如，您有一个 ID 为“delivery-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

沙盒请求

对于沙盒请求，请遵循上文端点中的指南，但向 /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

更新和增补项

您的每日批量 Feed 还应包含通过此 API 提交的任何更改。否则，批量更新将覆盖增量更改。

载荷

每个 POST 请求都必须包含请求参数以及包含商品目录架构中列出的任何实体类型的结构化数据的 JSON 载荷。

JSON 应与批量 Feed 中的 JSON 相同，但存在以下差异：

• 载荷正文的大小不得超过 5 MB。与批量 Feed 类似，我们建议您删除空格，以便容纳更多数据。
• 信封如下所示：

{
  "entity": {
    "data":"ENTITY_DATA",
    "vertical":"FOODORDERING"
  },
  "update_time":"UPDATE_TIMESTAMP"
}

在上面的载荷中，替换以下内容：

• ENTITY_DATA：序列化为字符串的 JSON 格式实体。JSON-LD 实体必须作为字符串在 data 字段中传递。
• UPDATE_TIMESTAMP（可选）：在您的系统中更新实体的时间戳。时间值不得是将来的时间。默认时间戳是 Google 收到请求的时间。通过增量请求发送实体时，实体版本控制在添加/更新请求的情况下也会使用 update_time 字段。

注意 ：使用 v1 商品目录架构时，即使您只需要更新顶级实体的一部分（例如菜单项的价格），也必须发送整个顶级实体。顶级实体 ID 是 POST 网址的一部分，因此不会包含在请求的 JSON-LD 载荷中。

更新实体

示例 1：更新餐厅

假设您急需更新某家餐厅的电话号码。您的更新包含整个餐厅的 JSON。

假设有一个批量 Feed，如下所示：

{
  "@type": "Restaurant",
  "@id": "restaurant12345",
  "name": "Some Restaurant",
  "url": "https://www.provider.com/somerestaurant",
  "telephone": "[phone]",
  "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": "[phone]",
      "streetAddress": "345 Spear St",
      "addressLocality": "San Francisco",
      "addressRegion": "CA",
      "postalCode": "94105",
      "addressCountry": "US",
      "latitude": 37.472842,
      "longitude": -122.217144
    },
    "vertical": "FOODORDERING"
  }
}

注意： 在上面的示例中，“data”未序列化为字符串，以提高可读性。

示例 2：更新菜单项价格

假设您需要更改菜单项的价格。与示例 1 中所述的一样，您的更新必须包含整个顶级实体（菜单）的 JSON，并且 Feed 使用 v1 商品目录架构。

假设有一个批量 Feed，如下所示：

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

注意： 在上面的示例中，“data”未序列化为字符串，以提高可读性。

添加实体

如需添加实体，请避免使用商品目录更新。请改为使用批量 Feed 流程，如v2 广告资源架构中所述。

移除实体

如需移除顶级实体，您可以使用经过稍微修改的端点，并在请求中使用 HTTP DELETE 而非 HTTP POST。

请勿使用 HTTP DELETE 移除顶级实体中的子实体，例如菜单中的菜单项。而是将子实体的移除视为对顶级实体的更新，其中子实体会从相关列表或参数中移除。

示例 1：删除顶级实体

假设您想在使用 v1 商品目录架构的 Feed 中删除一家餐厅。您还必须删除其服务和菜单。

菜单实体（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：移除子实体

如需从顶级实体中移除子实体，您需要发送从相应字段中移除子实体的顶级实体。以下示例假定 Feed 使用 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"
  }
}

注意 ：Google 会批量处理删除操作，而不是实时处理。

API 响应代码

调用成功并不意味着 Feed 有效或正确，而仅表示已进行 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 身份验证库，并假设 Feed 使用 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 Auth 库。

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 Auth 库。

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

使用场景

以下使用情形是增量更新、完整 Feed 更新以及 API 调用中高级内容的示例：

场景	顶级实体	说明和影响
停用服务	DisabledService	您因意外原因需要停用某项服务。 增量更新：发送的问题中的 Service 实体，将 @type 更改为 DisabledService，但将其他属性保持不变。 完整 Feed：请务必在 Google 下次提取之前，通过完整 Feed 更新实体，将 @type 设为 DisabledService，否则系统会重新启用该实体。
特定商品缺货	Menu	增量更新：对于给定的 MenuItem，发送封装 Menu 实体，并将 offer.inventoryLevel 设置为 0，所有其他数据保持不变。
菜单项价格变动	Menu	增量更新：发送封装 Menu 实体，并将 offer.price 设置为给定 MenuItem 的更新价格，所有其他数据保持不变。
添加新的顶级实体 仅适用于类型为 Menu、Restaurant 和 Service 的实体。	Menu、Restaurant、Service	例如，您需要为餐厅添加新菜单。 增量更新：发送新的菜单实体以及相应更新了字段 hasMenu 的餐厅实体。
永久删除顶级实体 仅适用于类型为 Menu、Restaurant 和 Service 的实体。	Menu、Restaurant、Service	增量更新：发送显式删除。 完整 Feed：请务必在 Google 下次提取数据之前从完整 Feed 中移除相应实体，否则系统会重新添加该实体。
在特定 Service 中添加新的配送区域	Service	增量 Feed：发送相关 Service 实体及其所有字段（就像您通常在完整 Feed 中所做的那样），并在 Service 的 areaServed 中指定新的配送区域。
更新了 Service 的预计送达时间	Service	增量更新型 Feed：发送的 Service 与 Feed 中的 Service 相同，但其 hoursAvailable.deliveryHours 会相应更新。
更新了 Service 中的配送价格	Service	增量 Feed：发送更新后的 offers.priceSpecification.price 的完整 Service。
在 Service 中更新外卖或外带营业时间	Service	增量更新型 Feed：发送的 Service 与 Feed 中的 Service 相同，但其 hoursAvailable 会相应更新。
Service（更改最低订购金额）	Service	增量 Feed：发送更新后的 Service.offers.priceSpecification.eligibleTransactionVolume 的完整 Service
永久删除 MenuItem	Menu	增量更新型 Feed：发送与 Feed 中相同的 Menu，但将此 MenuItem 从 hasMenuItems 列表中移除。

针对批量作业和增量更新的处理时间服务等级协议 (SLO)

通过批量更新或增量更新添加的实体将在 1-2 天内处理完毕。通过批量更新或删除的实体将在 2 小时内处理完毕，而通过增量更新更新的实体将在 5 分钟内处理完毕。系统会在 7 天后删除过时实体。

您可以向 Google 发送以下信息：

• 每天运行多个批量作业以确保您的商品目录保持最新状态，或者
• 每天一个批量作业和增量 API，以确保您的商品目录保持最新状态。