整合作業總覽

本地服務廣告 (LSA)，與整合商合作，在 Google.com 上顯示整合商的商家資訊 (或供應商)。本指南說明整合商如何提供供應商的本地服務廣告結構化資料。具體來說，我們會記錄整合商必須導入的 API 端點組合，才能與 LSA 整合。

詞彙

匯總者 (或合作夥伴)：這類合作夥伴會匯總提供者，並向這些提供者提供服務，而這些提供者的資料可能會提供給 LSA。

第三方供應商 (或商家資訊)：這些是個別的小型商家 (例如Joe’s plumbing)，這些商家可能與匯總工具存在業務關係。 集結網站會向在地生活服務提供這些商家的資訊。

總覽

整合商會透過動態饋給，向在地生活服務提供供應商 (商家) 的資料。每個動態饋給都包含多個供應商的資料。 在動態饋給中，單一供應商的資料會封裝在動態饋給項目中。每個動態消息也會指定動態消息時間戳記，表示動態消息的新鮮度。每個動態饋給也會指定動態饋給類型，可能是供應商簡介或供應商評論的資料，如下所述。

動態饋給類型

在初始整合階段，每個動態饋給可以是下列任一類型：

  • 商家檔案動態饋給：這個動態饋給提供商家檔案的相關資訊。每個動態消息項目都包含特定供應商的簡介資訊。包括不重複的商家 ID、商家名稱、服務地點、提供的服務、營業時間等。動態饋給項目也包含這個商家的放送中繼資料 (例如每月預算金額、廣告狀態等)。

  • 評論動態饋給：這個動態饋給提供供應商評論的相關資訊。每個動態饋給項目都封裝了特定供應商的詳細消費者評論清單。每則消費者評論都包含消費者姓名、評分 (1 到 5 分)、評論文字、評論時間戳記等。

如要進一步瞭解特定欄位及其語意，請參閱商家檔案動態饋給和評論動態饋給。

動態饋給擷取

動態消息資料會序列化為 JSON。如要提交資料，LSA 僅支援提取機制。我們計畫在日後支援推送機制。

提取機制

在提取機制中，匯總工具支援一組預先定義的 REST 端點 (網址)，可傳送及接收 JSON 物件。這與在網頁伺服器上代管一或多個檔案類似。LSA 會定期向這些網址發出 HTTP GET 要求，以擷取資料。如要瞭解預先定義的網址，請參閱下一節的 API 端點。

推送機制

在推送機制中，LSA 會提供端點供匯總工具呼叫及提供資料。在語意上，這與提取相同，但如果匯總工具想將特定資料推送至本機服務，這項功能可提供彈性。通訊協定中描述的所有語意、規則或限制，都同樣適用於推送和提取。

API 端點

集結網站應支援下列端點：一個用於商家檔案動態消息，另一個用於評論動態消息。

建議端點包含版本資訊，如下所示。首先請從 v1 開始。

端點 路徑
個人資料動態消息 /feeds/{version}/profile
評論動態饋給 /feeds/{version}/review

端點參數

參數 說明
maxresults 這是單一頁面可要求的動態饋給項目數量上限。
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 目錄中的資料夾和檔案清單，並確認檔案已複製到遠端系統

動態饋給類別

如前所述，每個動態消息都類似於檔案，且包含多個動態消息項目。每個動態饋給項目都會封裝特定供應商的資料 (專屬商家 ID)。每個動態消息也有時間戳記，表示動態消息的新鮮度。動態饋給類別會指定 LSA 解讀特定動態饋給的方式。動態饋給分為兩類，如下所述。

快照動態饋給會列出特定時間戳記的完整供應商清單 (位於集結網站下方)。處理這項快照動態消息後，適用下列語意：

  • 對於動態饋給中的任何供應商，系統都會更新 LSA 資料庫中該供應商的資料 (例如，如果是首次遇到，則會建立新的供應商；如果供應商已在先前的動態饋給中處理過，則會更新供應商資料)。

  • 如果匯總器下的任何供應商目前位於 LSA 資料庫中，但動態消息中沒有，系統就會刪除該供應商。

更新 (或增量) 動態饋給：在特定時間戳記，包含供應商的部分清單 (位於匯總工具下方)。處理增量動態饋給後，系統會套用下列語意：

  • 如果動態饋給中出現任何供應商，且該供應商是在先前的快照動態饋給中建立，系統就會更新 LSA 資料庫中該供應商的資料。(例如，如果這是第一次遇到供應商，系統會執行空運算)

  • 如果供應商目前位於 LSA 資料庫中，但動態饋給中沒有，則這項作業不會執行任何動作 (也就是說，這個供應商不會有任何變更)。

商家檔案和評論動態消息的語意略有不同。如需處理詳細資料，請參閱個別動態消息語意。

商家檔案動態饋給： * 擷取型快照動態饋給 * 推送型快照動態饋給 * 推送型更新動態饋給 評論動態饋給： * 擷取型快照動態饋給 * 推送型快照動態饋給

以下項目必須使用個別的設定檔動態饋給：

  1. 符合「Google 保證」或「Google 審核」徽章資格的供應商。

  2. 不符合徽章資格的供應商。

範例

快照動態消息

請注意，快照動態饋給會包含完整的供應商清單。舉例來說，如果匯總器想將 100 位供應商匯入 LSA，快照動態饋給應包含所有 100 位供應商的最新狀態。

運作方式

以下簡單範例說明設定檔動態消息的快照類別運作方式。

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

處理完快照 1 後，LSA 資料庫會包含 Pro 1 和 Pro 2。在處理 Snapshot 2 時，LSA 會更新 Pro 1、建立 Pro 3，並刪除 Pro 2。也就是說，處理完快照 2 後，LSA 資料庫會包含 Pro 1 和 Pro 3。

更新 (漸進式) 動態饋給

請注意，更新動態饋給包含匯總器下方的部分供應商清單。舉例來說，如果匯總器只想更新先前提供的 100 位供應商中的 5 位，更新動態饋給只需要包含這 5 位供應商的最新狀態。

運作方式

以下簡單範例說明「個人資料動態消息」的更新類別運作方式。

  • 更新 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。

快照和提取的影響

快照動態消息 + 提取機制有下列限制：

  • 合作夥伴可能需要幾小時才能新增或刪除供應商、更新商家檔案資訊、暫停廣告或變更預算。延遲時間與提取要求的頻率直接相關。
  • 如需緊急更新資料，我們可能需要手動支援一次性/臨時提取。

增量和推送支援的影響

開啟「更新動態饋給 + 推送」機制，代表以下改善項目：

  • 合作夥伴可以推送或提取快照動態饋給。如果合作夥伴不想維護端點 (用於提取)，可以改用推送功能，藉此降低端點維護成本。合作夥伴已在提取中支援快照動態消息，因此可以繼續在提取中提供快照。
  • 合作夥伴可以使用增量，只更新部分供應商的設定檔變更。這有助於提升個人資料的新鮮度。
  • 如要瞭解如何選擇快照與增量、推送與提取，請參閱這個章節，瞭解建議的整合方式。

合作夥伴必須定期提供快照動態饋給，無論是透過推送或提取。 這樣一來，如果錯過更新，LSA 就能處理回溯和系統復原等緊急狀況。

  • 合作夥伴應透過推送機制，每 2 小時推送一次快照設定檔動態消息，並每 6 小時檢查一次動態消息，確保基準資料為最新狀態。
  • 採用提取機制後，LSA 會每 2 小時提取一次快照設定檔動態饋給，並每 6 小時檢查一次動態饋給，確保基準資料保持最新狀態。
  • 合作夥伴只需要其中一種機制 (推送或提取)，不必同時使用，即可傳送快照動態饋給。

如要提升資料更新頻率，合作夥伴可以選擇透過推送方式傳送更新動態饋給。LSA 不會提取更新動態消息。

  • 更新動態消息可用於傳播上一個快照之後變更的項目，不必等待下一個快照。
  • LSA 建議供應商在兩次推送之間間隔超過 5 分鐘。
  • 建議在更新動態饋給中合理地組合動態饋給項目。如要更新 5 位供應商，LSA 偏好供應商推送 1 個更新動態饋給 (含 5 個動態饋給項目)，而不是推送 5 個更新動態饋給 (每個動態饋給含 1 個動態饋給項目)。
  • LSA 僅支援設定檔動態饋給的漸進式動態饋給，不支援評論動態饋給。

LSA 會遵守中繼資料中的 feedTimestampMicros 欄位，確保資料一致性。如果系統已擷取更新相同產品的新項目，就會略過時間戳記較舊的動態饋給項目，避免引入過時資訊。合作夥伴有責任在快照和更新動態饋給中，使用 feedTimestampMicros 正確反映資料的新鮮度。

合作夥伴應使用報表 API，取得各供應商的待開發客戶和費用資訊。