v1 增量目录更新

本部分介绍如何将具有时效性的 Feed 更新发送到 Google。借助增量更新 API，您可以更新和删除 几乎实时更新。

注意： 除非你已获得 豁免。如果您不确定是否需要实施广告资源更新， 请与您的 Google 顾问联系。

此功能主要用于您无法预见的更新， 例如紧急封闭通常，通过 增量更新 API 应在以下时间之内发布更改： 一周。如果您的更改不需要立即体现，您可以使用 而不是批量更新增量更新的处理时间不会超过 5 次 分钟。

设置

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

1. 按照创建和设置项目中列出的步骤进行操作， 创建项目。
2. 按照设置服务账号中列出的步骤操作 创建服务账号的权限。请注意，您必须是“所有者”的 项目以添加“Editor”该服务账号的角色
3. （可选，但建议执行）安装 Google 客户端库 以便在调用 API。下面提供的代码示例使用这些库。否则 需要按照使用 OAuth 2.0 访问 Google API 中的说明手动处理令牌交换。

端点

要将更新通知 Google，请向增量 Updates API，并包含更新和添加的载荷。 您使用的商品目录架构决定了将请求发送到哪个端点：

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 属性） 您要更新的数据 Feed 中对象的 ID。
• 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 中一样， 以下差异：

• 载荷正文的大小不得超过 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：更新餐厅

假设您急需更新某家餐厅的电话号码。您的 update 包含整个餐馆的 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 一样，您的 update 必须包含整个顶级实体（菜单）的 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”未序列化为 可读性。

添加实体

如需添加实体，请避免使用产品目录更新。您可以改为使用 请参阅 v2 广告资源架构部分中介绍的流程。

移除实体

要移除顶级实体，您需要使用一个略微修改的端点， 并在请求中使用 HTTP DELETE 而不是 HTTP POST。

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

示例 1：删除顶级实体

假设您想删除 Feed 中某餐厅的餐厅时使用 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：移除子实体

要从顶级实体中移除子实体，您可以发送顶级实体中的子实体， 实体，并且子实体已从相应字段中删除。以下 该示例假设 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，响应正文 会指明哪里出了问题。

例如，如果用户设置了“行业”值设为 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 Auth 库，并假设 Feed 使用 v1 广告资源架构如需了解替代解决方案，请参阅 针对“服务器到服务器”应用使用 OAuth 2.0。

更新实体

Node.js

此代码使用适用于 Node.js 的 Google auth 库。

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

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：请务必根据完整 Feed 更新实体 将@type设为DisabledService，然后再 下次提取时，该实体将被重新启用。
特定商品缺货	Menu	增量更新：发送封装 Menu 具有 offer.inventoryLevel 设置为 0 的实体。 MenuItem，所有其他数据保持不变。
菜单项价格变动	Menu	增量更新：发送封装 Menu 将 offer.price 设置为指定 MenuItem，所有其他数据保持不变。
添加新的顶级实体 仅适用于 Menu 类型的实体， Restaurant和Service。	Menu、Restaurant、Service	例如，您需要向餐厅添加新菜单。 增量更新：随餐厅一起发送新的菜单实体 实体及其字段 hasMenu 进行相应更新。
永久删除顶级实体 仅适用于 Menu 类型的实体， Restaurant和Service。	Menu、Restaurant、Service	增量更新：将 显式删除。 完整 Feed：务必先从完整 Feed 中移除实体，然后再 下次提取时，系统将重新添加该实体。
在特定Service添加新的送货区域	Service	增量更新型 Feed：将相关 Service 实体及其所有 字段保持不变，就像您在完整 Feed 中一样，同时具有新的送货区域 在 Service 的 areaServed 内指定。
更新预计送达时间（Service）	Service	增量 Feed：发送 Service 与 Feed，但其 hoursAvailable.deliveryHours 已更新 。
更新Service的运费	Service	增量更新 Feed：发送完整的 Service， “offers.priceSpecification.price”已更新。
更新Service的送货或外卖时间	Service	增量 Feed：发送 Service 与 Feed，但其 hoursAvailable 已更新 。
Service（更改最低订单金额）	Service	增量更新 Feed：发送完整的 Service， Service.offers.priceSpecification.eligibleTransactionVolume 已更新
永久删除“MenuItem”	Menu	增量 Feed：发送 Menu 与 但将此MenuItem从 hasMenuItems 列表。

批量作业和增量更新处理时间的 SLO

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

您可向 Google 发送以下信息：

• 每天多个批量作业，确保您的商品目录处于最新状态；或
• 每天一个批量作业和增量 API，让您的商品目录保持最新状态。