تقدّم واجهة Merchant API مرجعًا مخصّصًا هو
Homepage. يوفّر هذا المرجع طرقًا جديدة لإدارة المطالبة بملكية الصفحة الرئيسية، ما يقدّم إمكانات تتجاوز تلك التي توفّرها واجهة Content API for Shopping التقليدية.
للوصول إلى ميزات متجرك على الإنترنت، يجب اتّباع خطوتين: أولاً، إثبات الملكية، ثم المطالبة بملكية الموقع الإلكتروني لحسابك. لإكمال الخطوة الأخيرة،
استخدِم
accounts.homepage.claim.
الاختلافات الرئيسية
تُجري واجهة Merchant API عدة تغييرات مرتبطة بالصفحة الرئيسية مقارنةً بواجهة Content API for Shopping:
- مرجع مخصّص: توفّر واجهة Merchant API مرجعًا مميّزًا هو
Homepage(accounts.homepage) لجميع العمليات المرتبطة بالصفحة الرئيسية. في Content API for Shopping، كنت تستخدمaccounts.claimwebsiteلتنفيذ إجراء المطالبة، وكان عنوان URL للصفحة الرئيسية (website_url) جزءًا من مرجعAccount، وكانت حالة المطالبة (website_claimed) جزءًا من مرجعAccountStatus. - طُرق دقيقة: توفّر واجهة Merchant API طُرقًا محدّدة لإجراء ما يلي:
- استرداد تفاصيل الصفحة الرئيسية:
accounts.homepage.getHomepage - تعديل معرّف الموارد المنتظم (URI) للصفحة الرئيسية:
accounts.homepage.updateHomepage - المطالبة بملكية الصفحة الرئيسية:
accounts.homepage.claim - إلغاء المطالبة بملكية الصفحة الرئيسية:
accounts.homepage.unclaimاستخدَمت Content API for Shopping طريقةaccounts.claimwebsiteلإجراء المطالبة، وطريقةaccounts.updateلضبط عنوان URL (وإلغاء المطالبة بشكل فعلي من خلال ضبط عنوان URL فارغ)، وطريقةaccounts.get/accountstatuses.getلاسترداد عنوان URL و حالة المطالبة على التوالي.
- استرداد تفاصيل الصفحة الرئيسية:
- معلومات مركزية: يحتوي مرجع
Homepageفي Merchant API على كل منuri(عنوان URL للصفحة الرئيسية) والحالةclaimedمباشرةً. تعرض جميع الطرق التي تعمل على مرجعHomepageهذا المرجع، ما يقدّم ملاحظات فورية حول الحالة الحالية. في Content API for Shopping، لم تعرض طريقةaccounts.claimwebsiteالحالة المعدَّلة، وكان من الضروري إجراء طلبات منفصلة. - إلغاء المطالبة بشكل صريح: في Content API for Shopping، كان يتم
عادةً إلغاء المطالبة من خلال تعديل
Account.website_urlإلى سلسلة فارغة. توفر واجهة Merchant API طريقة مخصصة هيhomepage.unclaim. - الكتابة فوق المط101البة: تتيح كلتا واجهتَي برمجة التطبيقات مَعلمة
overwriteأثناء عملية المطالبة للاستحواذ على مطالبة من حساب آخر إذا كان من الممكن إثبات الملكية.
الطلبات
تستخدِم واجهة Merchant API نقاط نهاية مختلفة تستند إلى RESTful لإدارة جوانب مختلفة من الصفحة الرئيسية.
| وصف الطلب | Content API for Shopping | Merchant API |
|---|---|---|
| الحصول على تفاصيل الصفحة الرئيسية | accounts.get (لقراءة Account.website_url) وaccountstatuses.get (لقراءة AccountStatus.website_claimed) |
GET /accounts/v1/accounts/{account}/homepage |
| تعديل معرّف الموارد المنتظم (URI) للصفحة الرئيسية | accounts.update (ضبط Account.website_url) |
PATCH /accounts/v1/accounts/{account}/homepage |
| المطالبة بملكية الصفحة الرئيسية أو إعادة إثباتها | POST /content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite (تم تنفيذه على Account.website_url الذي تم ضبطه باستخدام accounts.update) |
POST /accounts/v1/accounts/{account}/homepage:claim |
| إلغاء المطالبة بملكية الصفحة الرئيسية | accounts.update (ضبط Account.website_url على سلسلة فارغة) |
POST /accounts/v1/accounts/{account}/homepage:unclaim |
المعرّفات
تم تبسيط عملية تحديد المراجع في Merchant API.
| وصف المعرّف | Content API for Shopping | Merchant API |
|---|---|---|
| معرّف الحساب للوصول إلى المرجع | merchantId (حساب بامتيازات متقدّمة) وaccountId (حساب فرعي) في المسار |
account (جزء من حقل name، مثل accounts/{account_id}/homepage) |
| معرّف مرجع الصفحة الرئيسية | لا ينطبق (ضمني في مرجع Account) |
name: accounts/{account_id}/homepage (يحدّد المرجع الفرعي Homepage) |
الطُرق
تُعدّ طريقة accounts.claimwebsite من Content API for Shopping، التي كانت تركّز على إجراء المطالبة، الآن جزءًا من مجموعة أوسع من الوظائف ضِمن مرجع Homepage في Merchant API.
| طريقة Content API for Shopping | طريقة Merchant API | التوفّر والملاحظات |
|---|---|---|
accounts.claimwebsite |
accounts.homepage.claim |
يبدأ هذا الإجراء مباشرةً المطالبة بملكية موقع إلكتروني أو يعيد إثباتها. ويعمل على uri الذي تم ضبطه سابقًا باستخدام homepage.update. ويتضمّن مَعلمة overwrite. ويعرض مرجع Homepage مع uri الحالي والحالة claimed. |
accounts.get (لقراءة Account.website_url) وaccountstatuses.get (لقراءة AccountStatus.website_claimed) |
accounts.homepage.getHomepage |
طريقة مخصّصة جديدة لاسترداد uri الحالي للصفحة الرئيسية والحالة claimed في طلب واحد |
accounts.update (لضبط Account.website_url) |
accounts.homepage.updateHomepage |
طريقة مخصّصة جديدة لضبط uri الصفحة الرئيسية أو تغييره |
accounts.update (ضبط Account.website_url على سلسلة فارغة كحل بديل لإلغاء المطالبة) |
accounts.homepage.unclaim |
طريقة مخصّصة جديدة لإلغاء المطالبة بملكية صفحة رئيسية بشكل صريح |
التغييرات التفصيلية في الحقول
تغيّرت طريقة تنظيم معلومات الصفحة الرئيسية والوصول إليها بشكل كبير، ما أدّى إلى استخدام مرجع Homepage الصريح في Merchant API.
| Content API for Shopping | Merchant API | الوصف |
|---|---|---|
merchantId (مَعلمة مسار لطريقة accounts.claimwebsite) |
name (مَعلمة مسار لطُرق Homepage، التنسيق: accounts/{account}/homepage) |
يتطابق جزء account من سلسلة name في Merchant API مع accountId من Content API for Shopping. |
accountId (مَعلمة مسار لطريقة accounts.claimwebsite) |
name (مَعلمة مسار لطُرق Homepage، التنسيق: accounts/{account}/homepage) |
معرّف الحساب المحدّد الذي تتم إدارة صفحته الرئيسية |
overwrite (قيمة منطقية في نص ContentAccountsClaimwebsiteRequest وAccountsCustomBatchRequestEntry) |
ClaimHomepageRequest.overwrite (قيمة منطقية في homepage.claim نص الطلب) |
اختياريّ. إذا كانت القيمة true، تتم محاولة المطالبة بملكية الموقع الإلكتروني، ما قد يؤدي إلى إزالة مطالبة حالية من حساب آخر إذا كان من الممكن إثبات الملكية من خلال الحساب الذي يقدّم الطلب. |
Account.website_url (حقل في مرجع Account، يتم ضبطه باستخدام accounts.update، وقراءته باستخدام accounts.get) |
Homepage.uri (حقل في مرجع Homepage) |
معرّف الموارد المنتظم (URI) (عنوان URL) للصفحة الرئيسية للمتجر في Merchant API، هذا حقل صريح ضِمن مرجع Homepage. يتم ضبطه باستخدام accounts.homepage.updateHomepage وتعرضه جميع طُرق Homepage. |
AccountStatus.website_claimed (حقل في مرجع AccountStatus، تتم قراءته باستخدام accountstatuses.get) |
Homepage.claimed (حقل منطقي output_only في مرجع Homepage) |
يشير إلى ما إذا تم المطالبة بملكية uri وإثباتها تتوفّر هذه الحالة مباشرةً في مرجع Homepage الذي تعرضه جميع طُرق Merchant API المرتبطة به. |
| لا ينطبق | UpdateHomepageRequest.update_mask accounts.homepage.updateHomepage معلمة نص طلب) |
قناع حقل اختياري لـ homepage.update لتحديد الحقول (مثل uri) التي يتم تعديلها في مرجع Homepage |