Listings APIListings API
登入

已連接的帳戶

連結 Google、Facebook 和 Apple Business Connect 帳戶，將其商家資訊與地點配對，並透過 client.connected_accounts 中斷帳戶連結。

所有已連結帳號的方法都位於 client.connected_accounts 下。已連結帳號是指已授權平台存取的 Google Business Profile、Facebook Pages 或 Apple Business Connect 登入帳號，以您從 connected_accounts.list 取得的 connectedAccountId 識別。

連結方式有 2 種。批次流程會授權整個發布平台帳號，然後將其商家資訊與您的地點配對。單一地點流程會為 1 個地點建立 1 個 OAuth 連結，適合用於應用程式逐一連結商店的情況。接受 location_id 的方法支援數字或 base64 編碼的 ID，請參閱地點 ID。

配對流程

批次連結完成後，發布平台的商家資訊尚未連結至您的地點。呼叫 trigger_matches 將配對工作加入佇列，輪詢 details 直到 requestMatchesStatus 的值為 MATCH_COMPLETED，使用 suggestions 讀取配對結果，再使用 confirm_matches 提交您要採用的配對。若略過 trigger_matches，suggestions 將保持空白。

connected_accounts.connect_google

建立用於授權整個 Google Business Profile 帳號的 URL。將使用者導向該 URL，之後使用者會返回 success_url 或 error_url。連結的有效期限為 24 小時。

Python
client.connected_accounts.connect_google(    success_url: str,    error_url: str,) -> APIObject
Python
link = client.connected_accounts.connect_google(  "https://app.example.com/onboarding/google/done",  "https://app.example.com/onboarding/google/retry",)print(link.url)

傳回 bulkConnectLinkForGoogle 物件。讀取 url，並檢查 success 和 errors。這 2 個重新導向 URL 都必須是絕對 https URL。請參閱連結 Google 帳號。

connected_accounts.connect_facebook

與 connect_google 相同，但適用於 Facebook Pages 帳號。有效期限為 24 小時。

Python
client.connected_accounts.connect_facebook(    success_url: str,    error_url: str,) -> APIObject
Python
link = client.connected_accounts.connect_facebook(  "https://app.example.com/onboarding/facebook/done",  "https://app.example.com/onboarding/facebook/retry",)print(link.url)

傳回 bulkConnectLinkForFacebook 物件，包含相同的 url、success 和 errors 欄位。請參閱連結 Facebook 帳號。

connected_accounts.oauth_url

建立將 1 個發布平台商家檔案連結至 1 個地點的 URL。若您已知道使用者要連結哪個地點，請使用此方法，無須執行配對步驟。有效期限為 24 小時。

Python
client.connected_accounts.oauth_url(    location_id: str | int,    site: str,    success_url: str,    error_url: str,) -> APIObject
參數型別說明
location_idstr | int要附加商家檔案的地點，以數字或 base64 表示。
sitestrGOOGLE、FACEBOOK 或 APPLE。SDK 會在傳送前將其轉為大寫。
success_urlstr成功時使用者返回的絕對 https URL。
error_urlstr失敗時使用者返回的絕對 https URL。
Python
link = client.connected_accounts.oauth_url(  16808,  site="google",  success_url="https://app.example.com/locations/16808?connected=1",  error_url="https://app.example.com/locations/16808?connected=0",)print(link.url)

傳回 createConnectUrl 物件。若重新導向 URL 是相對 URL 或無法解析，則會傳回 success: true，其中 url 為 null，因此請檢查 url 本身，而不只是 success。連結僅能使用 1 次，因此每次嘗試都請建立新的連結。請參閱為單一地點建立 OAuth 連結 URL。

connected_accounts.list

列出已連結至您帳號的 Google 和 Facebook 帳號。您可以在此取得後續每次呼叫所需的 connectedAccountId。

Python
client.connected_accounts.list(    *,    publisher: str | None = None,    status: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
參數型別說明
publisherstr僅包含單一發布平台的帳號。
statusstr僅包含處於單一連線狀態的帳號，例如 CONNECTED。
pageint從 1 開始的頁碼。
per_pageint每頁筆數。以 perPage 傳送。
Python
accounts = client.connected_accounts.list(status="CONNECTED", per_page=50)for account in accounts.records:  print(account.connectedAccountId, account.email, account.connectedLocationsCount)print(accounts.pageInfo.totalRecords)

傳回 connectedAccountsInfo 物件：包含 records，以及內含 hasNextPage、totalPages 和 totalRecords 的 pageInfo。排序固定依帳號電子郵件地址遞增排列。請參閱列出已連結帳號。

connected_accounts.details

依 ID 取得 1 個已連結帳號。執行 trigger_matches 後輪詢此方法，並等待 requestMatchesStatus 變為 MATCH_COMPLETED。

Python
client.connected_accounts.details(connected_account_id: str) -> APIObject
Python
account = client.connected_accounts.details("4f712c17-4f95-42dd-90f4-97171a2e67b5")print(account.details.get("status"))print(account.details.get("requestMatchesStatus"))

傳回 connectedAccountDetails 物件。欄位位於 details 下：status、connectedAccountType、connectedLocationsCount、connectivityIssue、requestMatchesStatus 和 lastFetchMatchesRequestedAt。connectivityIssue 不為 null 表示發布平台權杖需要重新授權。請參閱取得已連結帳號的詳細資料。

connected_accounts.listings

列出已連結帳號可存取的發布平台商家資訊，無論這些商家資訊是否已與您的地點配對。使用此方法向使用者顯示您已取得哪些存取權限。

Python
client.connected_accounts.listings(    connected_account_id: str,    *,    location_info: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
參數型別說明
connected_account_idstr要從中讀取商家資訊的已連結帳號。
location_infostr依商家資訊的名稱和地址進行自由文字篩選。
pageint從 1 開始的頁碼。
per_pageint每頁筆數。以 perPage 傳送。
Python
page = client.connected_accounts.listings(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",  location_info="Manhattan",  per_page=25,)for listing in page.records:  print(listing.locationName, listing.address, listing.accountTypeName)

此端點使用 POST，所有引數都放在請求主體中，而非查詢字串中；SDK 會為您建立該主體。傳回 connectedAccountListings 物件：包含 records 和 pageInfo。每筆記錄都包含 id、locationName、address、phone、accountTypeName 和 liveLink。請參閱擷取已連結帳號的商家資訊。

connected_accounts.trigger_matches

將工作加入佇列，以擷取指定帳號可存取的所有商家檔案，並與您的地點配對。請在批次連結完成後立即執行，並在新增地點後再次執行。

Python
client.connected_accounts.trigger_matches(    connected_account_ids: list[str],) -> APIObject
Python
result = client.connected_accounts.trigger_matches(  ["4f712c17-4f95-42dd-90f4-97171a2e67b5"],)print(result.success, result.failedIds)

傳回包含 success 和 failedIds 的 connectedAccountsTriggerMatches 物件。工作以非同步方式執行，因此 success: true 表示已加入佇列，而非已完成。請輪詢 details，直到 requestMatchesStatus 為 MATCH_COMPLETED 後，再讀取建議。請參閱觸發配對。

connected_accounts.suggestions

讀取配對工作找到的帳號商家資訊與您地點之間的配對結果。在確認這些配對之前，先顯示給使用者審閱。

Python
client.connected_accounts.suggestions(    connected_account_id: str,    *,    page: int | None = None,    per_page: int | None = None,) -> APIObject
Python
page = client.connected_accounts.suggestions(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",  per_page=50,)for match in page.records:  print(match.locationId, match.accountType, match.matchedDataDatabaseId)

傳回 connectionSuggestionsForAccount 物件：包含 records 和 pageInfo。每筆記錄都包含 locationId、accountType、matchedDataDatabaseId、locationInfo 和 suggestedLocationInfo。records 為空且伴隨 totalRecords: 0，通常表示配對工作尚未執行。請參閱列出連結建議。

connected_accounts.confirm_matches

提交建議的配對。確認後，發布平台商家資訊會開始與配對的地點同步。

Python
client.connected_accounts.confirm_matches(    match_record_ids: list[str],) -> APIObject
Python
result = client.connected_accounts.confirm_matches([  "R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M=",])print(result.success, result.failedIds)

傳回包含 success 和 failedIds 的 confirmConnectMatches 物件。建議記錄本身沒有 id：請依照確認配對 中的說明，使用記錄的 matchedDataDatabaseId 和 accountType 建立每筆配對記錄的 ID。

connected_accounts.folders

列出已連結 Google 帳號可存取的資料夾（Google 稱為帳號群組）。建立 Google 商家資訊時，請傳入選定的 folderId，將商家資訊放入正確的位置。

Python
client.connected_accounts.folders(    connected_account_id: str,    *,    folder_name: str | None = None,) -> list[APIObject]
Python
folders = client.connected_accounts.folders(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",)for folder in folders:  print(folder.folderId, folder.folderName, folder.locationCount)

傳回 getFoldersUnderGoogleAccount 清單。每個項目都有 folderId（原樣使用的 accounts/{id} 字串）、folderName 和 locationCount；當 Google 未回報數量時，最後一個欄位的值為 null。僅適用於 Google 類型的帳號。請參閱列出資料夾 和 listings.create_gmb。

connected_accounts.disconnect_google

中斷整個 Google 帳號的連結。透過該帳號配對的所有地點都會停止與 Google 同步。

Python
client.connected_accounts.disconnect_google(    connected_account_id: str,) -> APIObject
Python
result = client.connected_accounts.disconnect_google(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",)print(result.success)

傳回包含 success 的 gmbBulkDisconnect 物件。請參閱中斷 Google 帳號的連結。

connected_accounts.disconnect_facebook

中斷整個 Facebook Pages 帳號的連結。

Python
client.connected_accounts.disconnect_facebook(    connected_account_id: str,) -> APIObject
Python
result = client.connected_accounts.disconnect_facebook(  "9a41b8c0-7d2e-4c15-9f63-2b8e5ad71f04",)print(result.success)

傳回包含 success 的 fbBulkDisconnect 物件。請參閱中斷 Facebook 帳號的連結。

connected_accounts.oauth_disconnect

中斷 1 個地點與 1 個發布平台的連結，帳號其餘部分仍保持連結。此方法是 oauth_url 的反向操作。

Python
client.connected_accounts.oauth_disconnect(    location_id: str | int,    site: str,) -> APIObject

site 為 GOOGLE、FACEBOOK 或 APPLE，SDK 會在傳送前將其轉為大寫。

Python
client.connected_accounts.oauth_disconnect(16808, site="google")

傳回包含 success 和 errors 的 disconnectConnectedAccountsLocations 物件。請參閱中斷單一地點與發布平台的連結。

另請參閱