تقدّم 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 (حقل منطقي للقراءة فقط في مرجع Homepage) |
يشير إلى ما إذا تم المطالبة بـ uri وإثبات ملكيته تتوفّر هذه الحالة مباشرةً في مرجع Homepage الذي تعرضه جميع طُرق Merchant API المرتبطة به. |
| لا ينطبق | UpdateHomepageRequest.update_mask accounts.homepage.updateHomepage معلمة نص طلب) |
قناع حقل اختياري لـ homepage.update لتحديد الحقول (مثل uri) التي يتم تعديلها في مرجع Homepage |