集成概览

本地服务广告 (LSA) 与汇总商合作，以便在 Google.com 上展示其商家信息（或提供商）。本指南介绍了汇总商如何提供有关其提供商的 LSA 结构化数据。具体而言，我们会记录聚合器必须实现的一组 API 端点，以便与 LSA 集成。

术语库

聚合平台（或合作伙伴）：这些合作伙伴会聚合向其提供服务的提供商，并且可能会向 LSA 提供这些提供商的数据。

第三方提供商（或商家信息）：这些是个人小型企业（例如，Joe’s plumbing）可能与汇总商存在业务关系。 聚合平台会向本地生活服务提供有关这些企业的信息。

概览

汇总平台将使用 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 将仅支持拉取机制。我们未来计划支持推送机制。

拉取机制

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

推送机制

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

API 端点

集合商家应支持以下端点：一个用于商家资料 Feed，一个用于评价 Feed。

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

端点 路径
个人资料 Feed /feeds/{version}/profile
查看 Feed /feeds/{version}/review

端点参数

Params 说明
maxresults 这是单个页面中可请求的 Feed 项数量上限。
nextpagetoken 用于获取下一页结果的分页令牌

端点身份验证

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

  • username“授权”（仅作说明之用）
  • password J9adfdsafc3RfMjpVU1yif5XMw”（仅作说明之用）

适用于 Push 的 SFTP Dropbox

Dropbox 路径：partnerupload.google.com:19321

警告：上传到此 SFTP 投放箱的文件会在 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 Category 用于指定 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。也就是说，在处理完 Snapshot 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 + 拉取机制意味着存在以下限制：

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

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

开放更新 Feed + 推送机制意味着以下改进：

  • 合作伙伴可以通过推送或拉取方式提供快照 Feed。对于不想维护端点（用于拉取）的合作伙伴，可以使用推送来降低端点维护费用。如果合作伙伴已支持拉取模式下的快照 Feed，则可以继续以拉取模式提供快照。
  • 合作伙伴可以使用增量来仅更新具有个人资料更改的部分提供商。这有助于提高个人资料数据的新鲜度。
  • 至于如何选择快照与增量、推送与拉取，请参阅本部分了解推荐的集成方法。

合作伙伴必须提供定期快照 Feed，无论是通过推送还是拉取方式。 这样一来，LSA 就可以在错过更新时处理回滚和系统恢复等紧急情况。

  • 借助推送机制，合作伙伴应每 2 小时推送一次快照配置文件 Feed，并每 6 小时查看一次 Feed，以保证基准数据的新鲜度。
  • 借助拉取机制，LSA 将每 2 小时拉取一次快照配置文件 Feed，并每 6 小时检查一次 Feed，以保证基准数据的新鲜度。
  • 合作伙伴只需使用一种机制（推送或拉取）即可传送快照 Feed，但不能同时使用这两种机制。

如果合作伙伴想要提高数据的新鲜度，可以选择通过推送发送更新 Feed。LSA 将不会拉取更新 Feed。

  • 更新 Feed 用于传播自上次快照以来的更改项，而无需等待下一次快照。
  • LSA 建议提供商在两次推送之间设置超过 5 分钟的间隔。
  • 建议在更新 Feed 中合理地捆绑 FeedItem。若要更新 5 个提供商，LSA 倾向于让提供商推送 1 个包含 5 个 FeedItem 的更新 Feed，而不是推送 5 个各包含 1 个 FeedItem 的更新 Feed。
  • LSA 仅支持个人资料 Feed 的增量更新型 Feed，不支持评价 Feed 的增量更新型 Feed。

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

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