RTO 主要用于您无法预见的更新，例如紧急关闭或定期更改的元数据（例如预计到达时间）。如果您不需要更改立即生效，可以改用批量 Feed 提取。实时更新最长需要 5 分钟才能处理完毕。
Google Cloud Platform 设置
- 设置 GCP 项目。您需要拥有一个 GCP 项目才能访问 RTU API。
- 授予编辑者访问权限 food-support@google.com
- 告知您的 Google 联系人 GCP 项目编号。您的 GCP 项目必须与您的 Action Center 账号相关联，才能实现实时更新。
- 启用 Maps Booking API：
- 在 GCP 中，依次前往 API 和服务 > 库。
- 搜索“Google Maps Booking API”。
- 找到沙盒实例（“Google Maps Booking API [开发者版本]”），然后点击启用
- 找到正式版实例（“Google Maps Booking API”），然后点击启用
- 为您的 GCP 项目创建一个具有“编辑者”角色的服务账号。如需了解详情，请参阅服务账号设置。
- 请务必将批量 Feed 上传到您要进行实时更新的环境。
- 对于 API 身份验证，我们建议您安装以您偏好的语言提供的 Google 客户端库。使用“https://www.googleapis.com/auth/mapsbooking”作为 OAuth 范围。以下代码示例使用这些库。否则，您需要手动处理令牌交换，如使用 OAuth 2.0 访问 Google API 中所述。
服务账号设置
您需要有服务账号才能向 Google API（例如实时更新 API）发出经过身份验证的 HTTPS 请求。
如需设置服务账号，请执行以下操作：
- 访问 Google Cloud Platform 控制台。
- 您在 Action Center 中的账号也有一个关联的 Google Cloud 项目。选择该项目（如果尚未选择）。
- 点击左侧菜单中的服务账号。
- 点击创建服务账号。
- 输入服务账号的名称，然后点击创建。
- 在选择角色部分，选择项目 > 编辑者。
- 点击继续。
- 可选：添加用户以向其授予对服务账号的访问权限，然后点击完成。
- 为您刚刚创建的服务账号点击更多 > 创建密钥。
- 选择 JSON 作为格式，然后点击创建。
- 生成新的公钥/私钥对后，将其下载到您的计算机。
使用 API
Real-time updates API 支持两种类型的操作：更新和删除。不支持通过实时更新 API 添加新实体。如果您在单个 API 请求中包含多个更新，则可以批量处理实时更新。您最多可以在单个 API 调用中批量更新 1,000 项。我们建议您尽可能采用基于触发器的方法（即在系统中发生数据更改时触发对 Google 的实时更新），而不是基于频率的方法（即每 X 分钟扫描一次系统以查看是否有更改）。
Real-time updates API 可在沙盒环境和生产环境中运行。沙盒环境用于测试 API 请求，生产环境用于更新面向端到端订购用户显示的内容。
- 沙盒 -
partnerdev-mapsbooking.googleapis.com - 正式版 -
mapsbooking.googleapis.com
端点
实时更新 API 公开了两个端点来处理传入的商品目录更新请求：
- 更新 -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - 删除 -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
您可以在 Actions Center 的账号和用户页面中找到 PARTNER_ID 参数，如下面的屏幕截图所示。
以上屏幕截图中的 PARTNER_ID 值 10000001 为例，在沙盒和生产环境中发送 API 请求的完整网址将如下例所示。
沙盒更新
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Sandbox DELETE
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
正式版更新
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
正式版删除
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
更新实体
如需更新商品目录中的实体，请在 HTTP POST 请求中使用 update 端点。每个 POST 请求都必须包含 10000001 参数以及包含您要更新的实体的 JSON 载荷。
注意：请确保您的每日数据 Feed 还包含通过实时更新 API 提交的所有更改。否则，您的数据可能会过时或过期。
更新请求载荷
请求正文是一个包含记录列表的 JSON 对象。每个记录都对应一个要更新的实体。它由 proto_record 字段和指示实体更新时间的 generation_timestamp 组成：
{
"records": [
{
"proto_record":"ServiceData PROTO",
"generation_timestamp":"UPDATE_TIMESTAMP"
}
]
}ServiceData PROTO：您要更新的 ServiceData 实体的 Proto 或 JSON 转换。UPDATE_TIMESTAMP：请务必添加实体在后端系统中生成的时间戳。如果未添加此字段，系统会将其设置为 Google 收到请求的时间。通过batchPush请求更新实体时，generation_timestamp字段用于实体版本控制。请参阅关系型商品目录架构中的时间值的预期格式。
- 载荷正文的大小不得超过 5 MB。
- 删除空格以减小大小。
- 一个
batchPush请求中最多可以包含 1,000 项更新。
示例
更新预计到达时间
假设您急需将送货服务的预计送达时间从 30 至 60 分钟更新为 60 至 90 分钟。您的更新必须包含整个服务实体的 JSON。
假设有一个服务实体，如下所示：
{ "service": { "service_id": "service/entity002", "service_type": "DELIVERY", "parent_entity_id": "entity002", "lead_time": { "min_lead_time_duration": "600s", "max_lead_time_duration": "1800s" }, "action_link_id": "delivery_link/entity002" } }
通过 HTTP POST 进行的实时更新如下所示（为方便阅读，请求正文采用了美化输出格式）：
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "3600" }, "max_lead_time_duration" : { "seconds": "5400" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }] }
更新多个实体
如需在单次 API 调用中更新多个餐厅实体，请在请求正文的 proto_record 字段中添加多个记录。
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "1800" }, "max_lead_time_duration" : { "seconds": "3600" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee", "fee_type" : "DELIVERY", "fixed_amount" : { "currency_code" : "USD", "units" : "10", "nanos" : "0" }, "service_ids": ["service/entity002"] } }, "generation_timestamp" : "2023-09-13T17:11:10.750Z" }] }
删除实体
如需从商品目录中删除实体，请在 HTTP POST 请求中使用 DELETE 端点。每个 POST 请求都必须包含 PARTNER_ID 参数以及包含要删除的实体的标识符的 JSON 载荷。
注意：请确保您的每日数据 Feed 还包含通过实时更新 API 提交的所有更改。否则，每日批量提取将覆盖您的实时更改。
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery" } }, "delete_time": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee" } }, "delete_time" : "2023-09-13T17:11:10.750Z" }] }
添加实体
请勿使用实时更新来添加新实体，因为这可能会导致数据不一致。请改用批量 Feed。
验证和 API 响应代码
系统会对实时更新 API 调用执行两种类型的验证：
- 请求级 - 这些验证会检查载荷是否遵循架构，以及每个
proto_record是否包含id和type字段。这些检查是同步的，结果会在 API 响应正文中返回。响应代码为 200 且 JSON 正文为空{}表示这些验证已通过，并且该请求中的实体已加入队列以进行处理。非 200 响应代码表示其中一个或多个验证失败，并且整个请求都被拒绝（包括载荷中的所有实体）。例如，如果proto_record缺少@type，则会返回以下错误响应：
{ "error": { "code": 400, "message": "Record:{...}", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.DebugInfo", "detail": "[ORIGINAL ERROR] generic::invalid_argument: Failed to parse one or more rtu records. Record:... The entity type could not be extracted from the entity value." } ] }
- 实体级：系统会根据架构对载荷中的每个实体 (proto_record) 进行验证。验证此阶段遇到的问题不会在 API 响应中报告。这些数据仅会在操作中心的 RTU 报告信息中心内报告。
注意：响应代码 200 并不表示所有实体都已成功提取。
API 配额
实时 API 更新的配额为每 60 秒 1,500 个请求，即平均每秒 25 个请求。超出配额时，Google 会返回以下错误消息：
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}如需解决该问题，请使用以指数方式增大的时间间隔再次尝试重新调用，直到成功为止。如果您经常用尽配额，请考虑在一个 API 请求中包含更多实体。一次 API 调用中最多可以包含 1,000 个实体。
处理时间实时更新
通过实时更新更新的实体会在 5 分钟内处理完毕。