Listings APIListings API
サインイン

接続済みアカウント

Google、Facebook、Apple Business Connectのアカウントを接続し、各アカウントの掲載情報を拠点に対応付け、client.connected_accountsで接続を解除します。

接続済みアカウントのメソッドはすべてclient.connected_accountsにあります。接続済みアカウントとは、プラットフォームへのアクセスを承認した1つのGoogle Business Profile、Facebook Pages、またはApple Business Connectのログインアカウントであり、connected_accounts.listから取得するconnectedAccountIdで識別されます。

接続方法は2つあります。一括接続フローでは、掲載先アカウント全体のアクセスを承認し、その掲載情報を拠点と照合します。単一拠点の接続フローでは、1つの拠点に対して1つのOAuthリンクを作成します。アプリで店舗を1つずつ接続する場合に使用します。location_idを受け取るメソッドは、数値またはbase64エンコードされたIDに対応しています。拠点IDを参照してください。

照合フロー

一括接続の後、掲載先の掲載情報はまだ拠点に紐付けられていません。trigger_matchesを呼び出して照合ジョブをキューに追加し、requestMatchesStatusがMATCH_COMPLETEDになるまでdetailsをポーリングし、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を確認してください。両方のリダイレクト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)

同じurl、success、errorsフィールドを持つbulkConnectLinkForFacebookオブジェクトを返します。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であるか解析できない場合は、null urlを伴うsuccess: trueが返されるため、successだけでなくurl自体を確認してください。リンクは1回のみ使用できるため、試行ごとに新しく作成してください。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
パラメーター型説明
publisherstr1つの掲載先のアカウントのみに絞り込みます。
statusstrCONNECTEDなど、1つの接続状態のアカウントのみに絞り込みます。
pageint1から始まるページ番号です。
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)

recordsと、hasNextPage、totalPages、totalRecordsを含むpageInfoで構成されるconnectedAccountsInfoオブジェクトを返します。並び順は、アカウントのメールアドレスの昇順に固定されています。接続済みアカウントの一覧取得を参照してください。

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掲載情報の名前と住所を対象とする自由入力テキストのフィルターです。
pageint1から始まるページ番号です。
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がそのボディを構築します。recordsとpageInfoで構成されるconnectedAccountListingsオブジェクトを返します。各レコードには、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は完了ではなくキューへの追加を意味します。候補を読み取る前に、requestMatchesStatusがMATCH_COMPLETEDになるまでdetailsをポーリングしてください。照合の開始を参照してください。

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)

recordsとpageInfoで構成されるconnectionSuggestionsForAccountオブジェクトを返します。各レコードには、locationId、accountType、matchedDataDatabaseId、locationInfo、suggestedLocationInfoが含まれます。totalRecords: 0でrecordsが空の場合は、通常、照合ジョブがまだ実行されていないことを意味します。接続候補の一覧取得を参照してください。

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、およびGoogleが件数を報告しない場合にnullとなるlocationCountが含まれます。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オブジェクトを返します。1つの拠点と掲載先の接続解除を参照してください。

関連情報