RTU 主要用于您无法预见的更新，例如紧急封闭或定期更改的元数据（如 ETA）。如果您的更改不需要立即体现出来，您可以改用批量 Feed 提取。实时更新的处理时间不超过 5 分钟。
Google Cloud Platform 设置
- 设置 GCP 项目。访问 RTU API 需要使用 GCP 项目。
- 授予编辑者访问权限 food-support@google.com
- 将 GCP 项目编号告知您的 Google 联系人。您的 GCP 项目必须与 Actions Center 账号相关联，实时更新才能正常运作。
- 启用 Maps Booking API：
- 在 GCP 中，转到 API 和服务 >媒体库。
- 搜索“Google Maps Booking API”。
<ph type="x-smartling-placeholder">
</ph> 
- 找到沙盒实例（“Google Maps Booking API（开发版”），然后点击启用
- 找到正式版实例（“Google Maps Booking API”），然后点击启用
<ph type="x-smartling-placeholder">
</ph> 
- 创建对您的 GCP 项目的具有 Editor 角色的服务账号。如需了解详情，请参阅服务账号设置。
- 请确保将批量上传文件上传至正在进行实时更新的环境。
- 对于 API 身份验证，我们建议您使用自己选择的语言安装 Google 客户端库。使用“https://www.googleapis.com/auth/mapsbooking”作为 OAuth 范围。下面提供的代码示例使用这些库。否则，您需要按照使用 OAuth 2.0 访问 Google API 中的说明手动处理令牌交换。
服务账号设置
您需要拥有一个服务账号才能向 Google API（例如实时更新 API）发出经过身份验证的 HTTPS 请求。
如需设置服务账号，请执行以下操作：
- 访问 Google Cloud Platform 控制台。
- 您在 Actions Center 中的账号也有一个与之关联的 Google Cloud 项目。选择该项目（如果尚未选择）。
- 点击左侧菜单中的服务账号。
- 点击创建服务账号。
- 输入服务账号的名称，然后点击创建。
- 对于选择角色，选择项目 >编辑器。
- 点击继续。
- 可选：添加用户以授予他们访问服务账号的权限，然后点击完成。
- 点击更多 >为您刚刚创建的服务账号创建密钥。
- 选择 JSON 作为格式，然后点击创建。
- 生成新的公钥/私钥对后，将其下载到您的计算机。
使用 API
Real-time Updates API 支持两种类型的操作：更新和删除。不支持通过实时更新 API 添加新实体。如果您在单个 API 请求中包含多项更新，则可以批量处理实时更新。单次 API 调用最多可以批量处理 1,000 项更新。如果可能，我们建议采用基于触发器的方法通过 RTU 发送更新（即系统中的数据发生更改时会触发向 Google 发送实时更新），而不是基于频率的方法（即每 X 分钟对系统进行一次扫描以查找更改）。
实时更新 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
沙盒删除
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 还包含通过 Real-time updates 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 响应中报告。它们仅在 Actions Center 的 RTU 报告信息中心内报告。
注意：200 响应代码并不意味着所有实体都已成功提取。
API 配额
实时 API 更新的配额为每 60 秒 1500 个请求，即平均每秒 25 个请求。超出配额时，Google 会返回以下错误消息：
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}
要解决此问题，请以指数级时间再次重试调用，直到成功为止。如果您经常用尽配额，请考虑在一个 API 请求中包含多个实体。一次 API 调用最多可以包含 1,000 个实体。
处理实时更新
通过实时更新更新的实体在 5 分钟内进行处理。