Listings APIListings API
Anmelden

Verbundene Konten

Über client.connected_accounts verbinden und trennen Sie Google-, Facebook- und Apple Business Connect-Konten und ordnen deren Einträge Standorten zu.

Alle Methoden für verbundene Konten befinden sich unter client.connected_accounts. Ein verbundenes Konto ist ein Google Business Profile-, Facebook Pages- oder Apple Business Connect-Konto, das der Plattform Zugriff gewährt hat und durch eine connectedAccountId identifiziert wird, die Sie über connected_accounts.list erhalten.

Es gibt zwei Möglichkeiten, eine Verbindung herzustellen. Beim Ablauf für mehrere Standorte wird der Zugriff auf ein gesamtes Plattformkonto autorisiert. Anschließend werden dessen Einträge Ihren Standorten zugeordnet. Beim Ablauf für einen einzelnen Standort wird ein OAuth-Link für einen Standort erstellt. Diesen Ablauf verwenden Sie, wenn Ihre App Filialen einzeln verbindet. Methoden, die eine location_id entgegennehmen, akzeptieren numerische oder base64-codierte IDs, siehe Standort-IDs.

Zuordnungsablauf

Nach dem Verbinden eines gesamten Kontos sind die Einträge der Plattform noch nicht mit Ihren Standorten verknüpft. Rufen Sie trigger_matches auf, um den Zuordnungsauftrag in die Warteschlange einzureihen, fragen Sie details wiederholt ab, bis requestMatchesStatus den Wert MATCH_COMPLETED hat, lesen Sie die Zuordnungen mit suggestions aus und übernehmen Sie dann die gewünschten Zuordnungen mit confirm_matches. Wenn Sie trigger_matches überspringen, bleibt suggestions leer.

connected_accounts.connect_google

Erstellen Sie eine URL, die den Zugriff auf ein gesamtes Google Business Profile-Konto autorisiert. Leiten Sie den Benutzer dorthin weiter; anschließend kehrt er zu success_url oder error_url zurück. Der Link ist 24 Stunden gültig.

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)

Gibt das bulkConnectLinkForGoogle-Objekt zurück. Lesen Sie url aus und prüfen Sie success und errors. Beide Weiterleitungs-URLs müssen absolute https-URLs sein. Siehe Ein Google-Konto verbinden.

connected_accounts.connect_facebook

Wie connect_google, jedoch für ein Facebook Pages-Konto. 24 Stunden gültig.

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)

Gibt das bulkConnectLinkForFacebook-Objekt mit denselben Feldern url, success und errors zurück. Siehe Ein Facebook-Konto verbinden.

connected_accounts.oauth_url

Erstellen Sie eine URL, die ein Profil auf einer Plattform mit einem Standort verbindet. Verwenden Sie diese Methode, wenn Sie bereits wissen, welchen Standort der Benutzer verbindet, sodass kein Zuordnungsschritt erforderlich ist. 24 Stunden gültig.

Python
client.connected_accounts.oauth_url(    location_id: str | int,    site: str,    success_url: str,    error_url: str,) -> APIObject
ParameterTypBeschreibung
location_idstr | intStandort, mit dem das Profil verknüpft werden soll, als numerische oder base64-codierte ID.
sitestrGOOGLE, FACEBOOK oder APPLE. Das SDK wandelt den Wert vor dem Senden in Großbuchstaben um.
success_urlstrAbsolute https-URL, zu der der Benutzer bei Erfolg zurückkehrt.
error_urlstrAbsolute https-URL, zu der der Benutzer bei einem Fehler zurückkehrt.
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)

Gibt das createConnectUrl-Objekt zurück. Bei einer relativen oder nicht parsebaren Weiterleitungs-URL wird success: true mit null url zurückgegeben; prüfen Sie daher url selbst und nicht nur success. Der Link kann nur einmal verwendet werden. Erstellen Sie daher für jeden Versuch einen neuen Link. Siehe Eine OAuth-Verbindungs-URL für einen Standort erstellen.

connected_accounts.list

Listen Sie die Google- und Facebook-Konten auf, die mit Ihrem Konto verbunden sind. Hier erhalten Sie die connectedAccountId, die jeder spätere Aufruf benötigt.

Python
client.connected_accounts.list(    *,    publisher: str | None = None,    status: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
ParameterTypBeschreibung
publisherstrNur Konten einer bestimmten Plattform.
statusstrNur Konten mit einem bestimmten Verbindungsstatus, zum Beispiel CONNECTED.
pageintSeitennummer, beginnend bei 1.
per_pageintSeitengröße. Wird als perPage gesendet.
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)

Gibt das connectedAccountsInfo-Objekt zurück: records sowie pageInfo mit hasNextPage, totalPages und totalRecords. Die Sortierung ist fest auf die E-Mail-Adresse des Kontos in aufsteigender Reihenfolge eingestellt. Siehe Verbundene Konten auflisten.

connected_accounts.details

Rufen Sie ein verbundenes Konto anhand seiner ID ab. Fragen Sie es nach trigger_matches wiederholt ab und warten Sie, bis requestMatchesStatus den Wert MATCH_COMPLETED erreicht.

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"))

Gibt das connectedAccountDetails-Objekt zurück. Die Felder befinden sich unter details: status, connectedAccountType, connectedLocationsCount, connectivityIssue, requestMatchesStatus und lastFetchMatchesRequestedAt. Wenn connectivityIssue nicht null ist, muss das Plattform-Token erneut autorisiert werden. Siehe Details eines verbundenen Kontos abrufen.

connected_accounts.listings

Listen Sie die Plattformeinträge auf, auf die ein verbundenes Konto zugreifen kann, unabhängig davon, ob sie einem Ihrer Standorte zugeordnet sind. Zeigen Sie dem Benutzer damit, auf welche Einträge Sie Zugriff erhalten haben.

Python
client.connected_accounts.listings(    connected_account_id: str,    *,    location_info: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject
ParameterTypBeschreibung
connected_account_idstrVerbundenes Konto, dessen Einträge ausgelesen werden sollen.
location_infostrFreitextfilter für den Namen und die Adresse des Eintrags.
pageintSeitennummer, beginnend bei 1.
per_pageintSeitengröße. Wird als perPage gesendet.
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)

Dieser Endpunkt verwendet POST und nimmt alle Argumente im Request-Body entgegen, nicht im Query-String; das SDK erstellt diesen Body für Sie. Gibt das connectedAccountListings-Objekt zurück: records sowie pageInfo. Jeder Datensatz enthält id, locationName, address, phone, accountTypeName und liveLink. Siehe Einträge eines verbundenen Kontos abrufen.

connected_accounts.trigger_matches

Reihen Sie den Auftrag in die Warteschlange ein, der alle Profile abruft, auf die die angegebenen Konten zugreifen können, und sie mit Ihren Standorten abgleicht. Führen Sie ihn direkt nach dem Verbinden eines gesamten Kontos und erneut nach dem Hinzufügen von Standorten aus.

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)

Gibt das connectedAccountsTriggerMatches-Objekt mit success und failedIds zurück. Die Verarbeitung erfolgt asynchron, daher bedeutet success: true, dass der Auftrag in die Warteschlange eingereiht wurde, nicht dass er abgeschlossen ist. Fragen Sie details wiederholt ab, bis requestMatchesStatus den Wert MATCH_COMPLETED hat, bevor Sie Vorschläge auslesen. Siehe Zuordnung auslösen.

connected_accounts.suggestions

Lesen Sie die Zuordnungen aus, die der Zuordnungsauftrag zwischen den Einträgen des Kontos und Ihren Standorten gefunden hat. Zeigen Sie diese dem Benutzer zur Prüfung, bevor Sie sie bestätigen.

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)

Gibt das connectionSuggestionsForAccount-Objekt zurück: records sowie pageInfo. Jeder Datensatz enthält locationId, accountType, matchedDataDatabaseId, locationInfo und suggestedLocationInfo. Ein leeres records mit totalRecords: 0 bedeutet in der Regel, dass der Zuordnungsauftrag noch nicht ausgeführt wurde. Siehe Verbindungsvorschläge auflisten.

connected_accounts.confirm_matches

Übernehmen Sie vorgeschlagene Zuordnungen. Nach der Bestätigung beginnt die Synchronisierung des Plattformeintrags mit dem zugeordneten Standort.

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)

Gibt das confirmConnectMatches-Objekt mit success und failedIds zurück. Ein Vorschlagsdatensatz hat keine eigene id: Bilden Sie die ID jedes Zuordnungsdatensatzes aus dessen matchedDataDatabaseId und accountType, wie unter Zuordnungen bestätigen beschrieben.

connected_accounts.folders

Listen Sie die Ordner auf, auf die ein verbundenes Google-Konto zugreifen kann (Google bezeichnet sie als Kontogruppen). Übergeben Sie beim Erstellen eines Google-Eintrags die ausgewählte folderId, damit der Eintrag im richtigen Ordner erstellt wird.

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)

Gibt die getFoldersUnderGoogleAccount-Liste zurück. Jedes Element enthält folderId (eine unverändert verwendete accounts/{id}-Zeichenfolge), folderName und locationCount, das den Wert null hat, wenn Google keine Anzahl meldet. Nur für Konten vom Typ Google. Siehe Ordner auflisten und listings.create_gmb.

connected_accounts.disconnect_google

Trennen Sie die Verbindung zu einem gesamten Google-Konto. Alle über dieses Konto zugeordneten Standorte werden nicht mehr mit Google synchronisiert.

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)

Gibt das gmbBulkDisconnect-Objekt mit success zurück. Siehe Die Verbindung zu einem Google-Konto trennen.

connected_accounts.disconnect_facebook

Trennen Sie die Verbindung zu einem gesamten Facebook Pages-Konto.

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)

Gibt das fbBulkDisconnect-Objekt mit success zurück. Siehe Die Verbindung zu einem Facebook-Konto trennen.

connected_accounts.oauth_disconnect

Trennen Sie die Verbindung eines einzelnen Standorts zu einer einzelnen Plattform, während die übrigen Verbindungen des Kontos bestehen bleiben. Dies ist die Gegenoperation zu oauth_url.

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

site ist GOOGLE, FACEBOOK oder APPLE, und das SDK wandelt den Wert vor dem Senden in Großbuchstaben um.

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

Gibt das disconnectConnectedAccountsLocations-Objekt mit success und errors zurück. Siehe Die Verbindung eines einzelnen Standorts zu einer Plattform trennen.

Siehe auch