集成概览

本地生活服务广告 (LSA) 要与集合商家合作，在 Google.com 上展示其商家信息（或提供商）。在本指南中，我们将介绍集合商家可以如何提供其提供商的 LSA 结构化数据。具体而言，我们记录了为与 LSA 集成而必须实现的 API 端点集合集。

术语库

集合商家（或合作伙伴）：是指汇总了其提供服务的提供商及其数据可能会提供给 LSA 的合作伙伴。

第三方提供商（或商家信息）：是指具体的小型企业（例如他与集合商建立了业务关系。这些聚合信息网站会向本地生活服务提供这些商家的相关信息。

概览

集合商家将使用 Feed 向本地生活服务提供其提供商（商家）的相关数据。每个 Feed 都包含多个提供商的相关数据。 在 Feed 中，一个提供商的相关数据由 Feed 项封装。每个 Feed 还指定了表示 Feed 新鲜度的 Feed 时间戳。每个 Feed 还会指定一个 Feed 类型：可以是有关提供商资料或提供商评价的数据，如下所述。

Feed 类型

对于初始集成，每个 Feed 可能是以下 Feed 类型之一：

  • 配置文件 Feed：此 Feed 提供提供商资料的相关信息。每个 Feed 项都会封装特定提供商的个人资料信息。这包括唯一商家 ID、商家名称、服务地点、提供的服务、营业时间等。Feed 项还包含此商家的投放元数据（例如，每月预算金额、广告状态等）。

  • 评价 Feed：此 Feed 提供关于提供商评价的信息。每个 Feed 项都封装了特定提供商的详细消费者评价列表。每条消费者评价都包含消费者名称、评分（1 - 5 条）、评价文字、评价时间戳等。

如需详细了解特定字段及其语义，请参阅配置文件 Feed 和评价 Feed。

Feed 提取

Feed 数据已序列化为 JSON。如需提交数据，LSA 将仅支持拉取机制。我们未来会制定相关计划来支持推送机制。

拉取机制

在拉取机制中，聚合器支持一组发送和接收 JSON 对象的预定义 REST 端点（网址）。这类似于在网络服务器上托管一个或多个文件。LSA 会定期向这些网址发出 HTTP GET 请求来提取数据。如需详细了解预定义网址，请参阅 API 端点的下一部分。

推送机制

在推送机制中，LSA 将为聚合器提供一个端点以调用和提供数据。在语义上，这与拉取相同，但在聚合器想要将特定数据推送到本地服务的情况下提供了灵活性。协议中所述的所有语义、规则或约束均以相同的方式适用于推送和拉取。

API 端点

聚合器应支持以下端点：一个用于配置文件 Feed，另一个用于评价 Feed。

我们建议端点包含如下版本信息。我们从 v1 开始。

端点 路径
配置文件 Feed /feeds/{version}/profile
查看 Feed /feeds/{version}/review

端点参数

参数 说明
maxresults 这是在一个页面中可以请求多少个 Feed 项。
nextpagetoken 获取下一页结果的分页令牌

端点身份验证

Authentication 使用 HTTP 基本访问身份验证方法：使用 base64 编码的用户名和密码进行身份验证。下面提供了一个示例。

  • username“授权”（为便于说明）
  • password J9adfdsafc3RfMjpVU1yif5XMw”（为便于说明）

用于推送的 SFTP Dropbox

Dropbox 路径：partnerupload.google.com:19321

警告：加载到此 SFTP Dropbox 的文件会在 24 小时后自动删除。

端点身份验证

  • 公钥/私钥对（推荐）

    • 请按照此处的教程生成密钥对。
    • 向 LSA 发送公钥并保留私钥以进行身份验证
    • LSA 会使用公钥生成用户名并发回给聚合信息网站

  • 密码身份验证

    • LSA 将生成用户名和密码并发回给集合商家

SFTP 命令快速参考

  1. 登录。使用此命令登录。（如果您不使用私钥，请省略 -i ）。

    sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.com

  2. 复制文件。将文件复制到远程系统。您可以使用 lls/lcd 将 ls/cd 导入本地系统以查找文件。然后复制文件：

    put <path_to_local_file>

  3. 验证。使用 ls 查看 SFTP 目录中的文件夹和文件列表，并验证您的文件是否已复制到远程系统

Feed 类别

如前所述，每个 Feed 都与一个文件类似，由多个 Feed 项组成。每个 Feed 项都会封装特定提供商的相关数据（唯一商家 ID）。每个 Feed 还有一个时间戳，用于指明此 Feed 的新鲜度。Feed 类别指定了 LSA 如何解读给定 Feed。如下所述，Feed 分为两类。

快照 Feed 包含特定时间戳的提供方（集合商家名下）的完整列表。处理此快照 Feed 后，系统将应用以下语义：

  • 对于 Feed 中存在的任何提供商，系统将更新 LSA 数据库中此提供商的数据（例如，如果首次遇到该提供商，请创建新提供商；如果提供商在早期 Feed 中进行了处理，则更新提供商数据）。

  • 如果集合商家目前存在于 LSA 数据库中，但 Feed 中缺少该提供商，则该提供商将被删除。

更新（或增量）Feed 包含特定时间戳的部分提供商（位于集合商家下）。处理完增量 Feed 后，系统将应用以下语义：

  • 对于 Feed 中存在的任何提供商，如果该提供商是在较早的快照 Feed 中创建的，则系统会在 LSA 数据库中更新该提供商的数据。（例如，如果首次遇到提供程序，它将是一个空操作）

  • 对于当前存在于 LSA 数据库中但在 Feed 中缺失的任何提供商，这是一个空操作（即，此提供商不会发生任何变化）。

商家资料 Feed 与评价 Feed 的语义略有不同。如需了解处理详情，请参阅各个 Feed 语义。

配置文件 Feed： * 基于拉取的快照 Feed * 基于推送的快照 Feed * 基于推送的更新 Feed * 基于拉取的快照 Feed * 基于推送的快照 Feed

以下各项需要单独的配置文件 Feed：

  1. 被视为有资格获得 Google 保证徽章或 Google 筛查计划徽章的提供商。

  2. 没有资格获得徽章的提供商。

示例

快照 Feed

回想一下，快照 Feed 将包含完整的提供商列表。例如，如果集合商家希望将 100 个提供商提取到 LSA 中，则快照 Feed 应包含所有 100 个提供商的最新状态。

运作方式

下面是一个简单的示例，展示了个人资料 Feed 的快照类别的工作原理。

  • 快照 1 包含 Pro 1、Pro 2
  • 快照 2 包含 Pro 1、Pro 3

处理快照 1 后，LSA 数据库将拥有 Pro 1 和 Pro 2。在处理快照 2 的过程中，LSA 将更新 Pro 1，创建 Pro 3 并删除 Pro 2。也就是说，快照 2 处理完毕后，LSA 数据库将具有 Pro 1 和 Pro 3。

更新（增量）Feed

回想一下，更新 Feed 包含聚合器下的部分提供程序。例如，如果聚合器想要更新之前提供的 100 个提供商中的 5 个，则更新 Feed 只需包含这 5 个提供商的最新状态。

运作方式

下面是一个简单的示例，展示了“配置文件 Feed”的更新类别的工作原理。

  • 更新 1：Pro 1、Pro 2
  • 更新 2：Pro 1、Pro 3

处理更新 1 后，LSA 数据库将拥有 Pro 1 和 Pro 2。在更新 2 的处理过程中，LSA 会更新 Pro 1 并创建 Pro 3。请注意，Pro 2 不会受到影响。也就是说，更新 2 处理完毕后，LSA 数据库将拥有 Pro1、Pro2 和 Pro 3。

快照和拉取的影响

快照 Feed + 拉取机制隐含以下限制：

  • 合作伙伴可能要过几个小时才会添加或删除提供方、更新个人资料信息、暂停广告或更改预算。延迟时间与拉取请求的频率直接相关。
  • 对于紧急数据更新，我们可能需要手动支持一次性/临时拉取。

增量支持和推送支持的影响

打开 Update Feed + push 机制意味着进行以下改进：

  • 合作伙伴可以通过推送或拉取传送快照 Feed。如果合作伙伴不想维护端点（用于拉取），则可使用推送来降低端点维护成本。合作伙伴已在拉取中支持快照 Feed，因此可以继续在拉取中传送快照。
  • 合作伙伴可以使用增量更新，仅更新包含一部分资料的提供商。这样可以提高配置文件的数据新鲜度。
  • 如需了解如何选择快照与增量、推送与拉取，请参阅本部分，了解推荐的集成方法。

合作伙伴需要定期发送快照 Feed，无论是通过推送还是拉取。这样一来，LSA 可以在错过更新时处理回滚和系统恢复等紧急问题。

  • 使用推送机制时，合作伙伴应每 2 小时推送一次快照配置文件 Feed，每 6 小时检查一次 Feed，以确保基准数据新鲜度。
  • 使用拉取机制时，LSA 会每 2 小时拉取一次快照配置文件 Feed，并每 6 小时审核一次 Feed，以确保基准数据新鲜度。
  • 合作伙伴只需使用其中一种机制（推送或拉取即可），但不需要同时采用这两种机制来传送快照 Feed。

（可选）想要提高数据新鲜度的合作伙伴可以通过推送发送更新 Feed。LSA 不会提取更新 Feed。

  • 更新 Feed 用于传播自上一个快照创建以来已更改的内容，而无需等待下一个快照。
  • LSA 建议提供程序两次推送之间的时间间隔超过 5 分钟。
  • 我们建议您在更新 Feed 中合理地捆绑 Feed 项。如需更新 5 个提供商，LSA 更倾向于推送 1 个包含 5 个 Feed 项的更新 Feed，而不是推送 5 个更新 Feed，每个 Feed 项各 1 个。
  • LSA 仅支持为配置文件 Feed 添加增量 Feed，不支持为评价 Feed 添加增量 Feed。

LSA 将遵循元数据中的 feedTimestampMicros 字段，以确保数据一致性。如果注入了更新同一专业人员的更新项，则系统会跳过时间戳较早的 Feed 项，以免引入过时内容。合作伙伴有责任在快照 Feed 和更新 Feed 中使用 feedTimestampMicros 正确反映数据新鲜度。

合作伙伴应使用 Reporting API 获取有关每个提供商潜在客户数量和费用的信息。