Listings APIListings API
تسجيل الدخول

الحسابات المتصلة

اربط حسابات Google وFacebook وApple Business Connect، وطابق إدراجات الأنشطة التجارية التابعة لها مع المواقع، وافصل الحسابات عبر client.connected_accounts.

جميع أساليب الحسابات المتصلة موجودة ضمن client.connected_accounts. الحساب المتصل هو حساب تسجيل دخول واحد إلى Google Business Profile أو Facebook Pages أو Apple Business Connect منح المنصة تفويضًا، ويُحدَّد بواسطة connectedAccountId تحصل عليه من connected_accounts.list.

هناك طريقتان للاتصال. يمنح مسار الاتصال الجماعي تفويضًا لحساب منصة نشر بالكامل، ثم يطابق إدراجات الأنشطة التجارية فيه مع مواقعك. ينشئ مسار الاتصال لموقع واحد رابط OAuth واحدًا لموقع واحد، وهو ما تحتاج إليه عندما يربط تطبيقك المتاجر واحدًا تلو الآخر. تقبل الأساليب التي تأخذ location_id معرّفات رقمية أو معرّفات مرمّزة بصيغة base64، راجع معرّفات المواقع.

مسار المطابقة

بعد الاتصال الجماعي، لا تكون إدراجات الأنشطة التجارية لدى منصة النشر مرتبطة بمواقعك بعد. استدعِ trigger_matches لإضافة مهمة المطابقة إلى قائمة الانتظار، واستعلم دوريًا من details حتى تصبح قيمة requestMatchesStatus هي MATCH_COMPLETED، واقرأ أزواج المطابقة باستخدام suggestions، ثم اعتمد ما تريده منها باستخدام confirm_matches. يؤدي تخطي trigger_matches إلى إبقاء suggestions فارغًا.

connected_accounts.connect_google

أنشئ عنوان URL يمنح تفويضًا لحساب Google Business Profile بالكامل. وجّه المستخدم إليه، وسيعود إلى 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. راجع ربط حساب 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عنوان URL مطلق يستخدم https ويعود إليه المستخدم عند النجاح.
error_urlstrعنوان URL مطلق يستخدم https ويعود إليه المستخدم عند الفشل.
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. إذا كان عنوان إعادة التوجيه نسبيًا أو تعذّر تحليله، تكون النتيجة success: true مع null url، لذا تحقق من url نفسه ولا تكتفِ بالتحقق من success. الرابط مخصص للاستخدام مرة واحدة، لذا أنشئ رابطًا جديدًا لكل محاولة. راجع إنشاء عنوان URL للاتصال عبر OAuth لموقع واحد.

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

اجلب حسابًا متصلًا واحدًا باستخدام معرّفه. استعلم دوريًا باستخدام هذا الأسلوب بعد 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)

يُرجع الكائن connectedAccountsTriggerMatches الذي يتضمن success وfailedIds. يُنفَّذ العمل بصورة غير متزامنة، لذا تعني 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)

يُرجع الكائن confirmConnectMatches الذي يتضمن success وfailedIds. لا يملك سجل الاقتراح id خاصًا به: أنشئ معرّف كل سجل مطابقة من matchedDataDatabaseId وaccountType في السجل، كما هو موضح في تأكيد المطابقات.

connected_accounts.folders

اعرض قائمة بالمجلدات (تسميها Google مجموعات الحسابات) التي يمكن لحساب Google متصل الوصول إليها. مرّر folderId الذي اخترته عند إنشاء إدراج نشاط تجاري على Google ليُنشأ في المكان الصحيح.

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 الذي تكون قيمته null عندما لا تُبلغ Google عن العدد. لحسابات نوع 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)

يُرجع الكائن gmbBulkDisconnect الذي يتضمن success. راجع فصل حساب 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)

يُرجع الكائن fbBulkDisconnect الذي يتضمن success. راجع فصل حساب 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")

يُرجع الكائن disconnectConnectedAccountsLocations الذي يتضمن success وerrors. راجع فصل موقع واحد عن منصة نشر.

انظر أيضًا