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 种连接方式。批量流程会对整个发布平台账号进行授权，然后将其商家信息与您的地点匹配。单地点流程为一个地点创建一个 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

创建一个用于将一个发布平台资料连接到一个地点的 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，并附带 null url，因此请检查 url 本身，而不只是 success。链接只能使用一次，因此每次尝试都要创建新链接。请参阅为一个地点创建 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 和 pageInfo，其中后者包含 hasNextPage、totalPages 和 totalRecords。排序固定为按账号电子邮件地址升序排列。请参阅列出已连接账号。

connected_accounts.details

根据 ID 获取一个已连接账号。在 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

断开一个地点与一个发布平台的连接，保留该账号的其他连接。此操作与 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 对象。请参阅断开一个地点与一个发布平台的连接。

另请参阅