Merchant API روشی قوی‌تر و شهودی‌تر برای مدیریت داده‌های محصولتان معرفی می‌کند. تغییر اصلی، جداسازی داده‌های محصول به دو منبع متمایز است: ProductInput برای ارسال داده‌هایتان و Product برای مشاهده نسخه نهایی پردازش‌شده، ازجمله وضعیت محصول و مشکلات. این ساختار جدید
تجربه‌ای قابل‌پیش‌بینی‌تر و شفاف‌تر ارائه می‌دهد.
این راهنما تفاوت‌های کلیدی را به شما نشان می‌دهد تا به شما کمک کند ادغام خود را از Content API for Shopping منتقل کنید. برای راهنمای دقیق درباره استفاده از ویژگی‌های جدید، به مدیریت محصولات مراجعه کنید.
تفاوت‌های اصلی
در اینجا مهم‌ترین تغییرات در نحوه مدیریت محصولات در Merchant API درمقایسه با Content API for Shopping آورده شده است:
منابع اختصاصی برای داده‌های ورودی و پردازش‌شده: Merchant API مدیریت محصول را به دو منبع تقسیم می‌کند. می‌توانید از منبع
ProductInputبرای درج، به‌روزرسانی، و حذف داده‌های محصولتان استفاده کنید. می‌توانید از منبع فقط خواندنیProductبرای مشاهده محصول نهایی پس‌از پردازش ورودی‌هایتان توسط Google، اعمال قوانین، و ترکیب داده‌ها از منابع تکمیلی استفاده کنید.کدبندی برای نام‌های محصول: می‌توانید از کدبندی unpadded base64url (RFC 4648 Section 5) برای هر دو فیلد
ProductInput.nameوProduct.nameاستفاده کنید. اگر نام محصول حاوی نویسه‌هایی باشد که Merchant API از آن‌ها استفاده می‌کند یا نویسه‌هایی که برای نشانی وب رزرو شده‌اند، کدبندی اجباری است. برای مثال، اگر نام محصول حاوی هریک از نویسه‌های زیر باشد، باید آن را کدبندی کنید:% . + / : ~ , ( * ! ) & ? = @ # $وضعیت محصول ادغام‌شده: سرویس
productstatusesبرداشته شده است. مشکلات اعتبارسنجی محصول و وضعیت‌های مقصد اکنون مستقیماً در منبعProductدر فیلدproductStatusگنجانده شده‌اند که بازیابی داده‌ها را ساده‌تر می‌کند.به‌روزرسانی‌های قابل‌پیش‌بینی محصول: روش جدید
productInputs.patchورودی محصول خاصی را مستقیماً اصلاح می‌کند. این بهبود قابل‌توجهی نسبت به Content API ویژه Shopping است که در آن به‌روزرسانی‌ها ممکن است به‌طور غیرمنتظره‌ای توسط بارگذاری‌های فید دیگر بازنویسی شوند. در Merchant API، به‌روزرسانی تا زمانی که آن ورودی محصول خاص دوباره به‌روزرسانی یا حذف شود باقی می‌ماند. به‌روزرسانی‌های محصول به‌جای منبع پردازش‌شدهProductروی منبعProductInputاعمال می‌شود.منبع داده‌تان را برای مدیریت تمیزتر داده‌ها انتخاب کنید: همه عملیات‌های نوشتن
productInputsاکنون به پارامتر پُرسمانdataSourceنیاز دارند، که باعث می‌شود منبع داده‌ای که درحال اصلاح آن هستید به‌طور صریح مشخص شود. این ویژگی به‌خصوص زمانی مفید است که چندین منبع داده ارائه می‌دهند.شناسه‌های منبع جدید: محصولات اکنون با منبع RESTful
nameبه‌جای فیلدidشناسایی می‌شوند. قالبaccounts/{account}/products/{product}است.بدون دسته‌های سفارشی: روش
custombatchدیگر دردسترس نیست. می‌توانید از درخواست‌های ناهمگام یا دسته‌بندی HTTP برای ارسال چند درخواست در یک تماس HTTP استفاده کنید.
دستورالعمل‌های منبع داده درطول انتقال
قبل‌از انتقال منابع داده، اکیداً توصیه می‌کنیم استراتژی منبع داده‌تان را انتخاب کنید.
برای اطمینان از انتقال بی‌دردسر و جلوگیری از مشکلاتی مانند سرقت پیشنهاد، این توصیه‌ها را دنبال کنید:
پایگاه داده‌تان را پر کنید: به‌جای فراخوانی
dataSources.listقبل‌از هر عملیات محصول، اکیداً توصیه می‌کنیم که پایگاه داده محلی‌تان را یک‌بار پر کنید. فیلد نامdataSourceرا به هر سابقه محصول اضافه کنید تا بتوانید شناسه صحیح را مستقیماً در درخواست‌هایتان ارائه دهید.ادغام و استفاده از منابع داده برای هر برچسب و زبان: Merchant API امکان ایجاد منبع داده را بدون مشخص کردن برچسب و زبان فراهم می‌کند و بنابراین اجازه می‌دهد محصولات با هر برچسب منبع داده و زبانی درج شوند. برای هر برچسب و زبان، از یک منبع داده استفاده کنید.
از محصولاتتان محافظت کنید: اگر از قوانین منبع داده استفاده می‌کنید،
products.getرا فراخوانی کنید تا قبل‌از به‌روزرسانی یا حذف محصول،dataSourceدقیق مرتبط با آن را پیدا کنید. این کار تضمین می‌کند که منبع موردنظر را اصلاح می‌کنید و از سرقت تصادفی پیشنهاد جلوگیری می‌کند.
درخواست‌ها
این بخش قالب‌های درخواست را برای Content API for Shopping و Merchant API مقایسه می‌کند.
| شرح درخواست | Content API for Shopping | میانای برنامه‌سازی کاربردی فروشنده |
|---|---|---|
| دریافت محصول | GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} |
GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product} |
| فهرست کردن محصولات | GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products |
GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products |
| درج محصول | POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products |
POST https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs:insert |
| به‌روزرسانی محصول | PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} |
PATCH https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput} |
| حذف محصول | DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} |
DELETE https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput} |
| دریافت وضعیت محصول | GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses/{productId} |
GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product} |
| فهرست کردن وضعیت‌های محصول | GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses |
GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products |
| دسته‌بندی چند درخواست | POST https://shoppingcontent.googleapis.com/content/v2.1/products/custombatch |
از درخواست‌های ناهمگام یا دسته‌بندی HTTP استفاده کنید |
شناسه‌ها
قالب شناسه‌های محصول در Merchant API به نام منبع REST استاندارد تغییر کرده است.
| شرح شناسه | Content API for Shopping | میانای برنامه‌سازی کاربردی فروشنده |
|---|---|---|
| شناسه محصول | رشته‌ای متشکل از بخش‌هایی که با دونقطه (:) از هم جدا شده‌اند.قالب: channel:contentLanguage:targetCountry:offerId یا channel:contentLanguage:feedLabel:offerId.مثال: online:en:US:sku123 |
رشته name منبع REST.قالب: accounts/{account}/products/{product} که {product} contentLanguage~feedLabel~offerId است.مثال: accounts/12345/products/en~US~sku123.کدبندی: کدبندی base64url بدون لایه توصیه می‌شود و درصورت وجود شناسه‌های محصولی که حاوی نویسه‌های استفاده‌شده توسط Merchant API یا نویسه‌های رزروشده نشانی وب هستند، اجباری است. |
روش‌ها
این جدول روش‌های Content API for Shopping و معادل‌های آن‌ها را در Merchant API نشان می‌دهد.
| روش Content API ویژه Shopping | روش Merchant API | دردسترس بودن و نکات |
|---|---|---|
products.get |
products.get |
محصول نهایی پردازش‌شده را بازیابی می‌کند. |
products.list |
products.list |
محصولات نهایی و پردازش‌شده را فهرست می‌کند. |
products.insert |
productInputs.insert |
ورودی محصول را درج می‌کند. به dataSource نیاز دارد. |
products.update |
productInputs.patch |
رفتار به‌طور قابل‌توجهی متفاوت است. این قانون ورودی محصول خاصی را به‌روز می‌کند و پایدار است. |
products.delete |
productInputs.delete |
ورودی محصول خاصی را حذف می‌کند. به dataSource نیاز دارد. |
products.custombatch |
دردسترس نیست | از درخواست‌های ناهمگام یا دسته‌بندی HTTP استفاده کنید. |
productstatuses.get |
products.get |
سرویس productstatuses برداشته شد. اطلاعات وضعیت اکنون بخشی از منبع Product است. |
productstatuses.list |
products.list |
سرویس productstatuses برداشته شد. اطلاعات وضعیت اکنون بخشی از منبع Product است. |
productstatuses.custombatch |
دردسترس نیست | از درخواست‌های ناهمگام یا دسته‌بندی HTTP استفاده کنید. |
تغییرات دقیق فیلد
این جدول فیلدهای مهمی را که در Merchant API تغییر کرده، اضافه شده، یا برداشته شده است برجسته می‌کند.
| Content API for Shopping | میانای برنامه‌سازی کاربردی فروشنده | شرح |
|---|---|---|
id |
name |
شناسه اصلی محصول اکنون منبع REST name است. کدبندی base64url بدون لایه توصیه می‌شود و درصورت وجود نام‌های محصولی که حاوی نویسه‌های استفاده‌شده توسط Merchant API یا نویسه‌های رزروشده نشانی وب هستند، اجباری است. |
مشخصه‌های مشخصات داده محصول سطح بالا (مثلاً title، price، link) |
productAttributes شیء |
مشخصه‌های محصول مانند title، price، و link دیگر فیلدهای سطح بالا نیستند. اکنون آن‌ها در شیء productAttributes در هر دو منبع Product و ProductInput گروه‌بندی شده‌اند. این کار ساختار منبع تمیزتر و سازمان‌یافته‌تری را فراهم می‌کند. |
targetCountry |
feedLabel |
نام منبع اکنون به‌جای targetCountry از feedLabel استفاده می‌کند تا با عملکرد Merchant Center مطابقت داشته باشد. |
feedId |
dataSource (پارامتر پُرسمان) |
نام dataSource اکنون پارامتر پُرسمان الزامی برای همه روش‌های نوشتن productInputs (insert، update، delete) است. |
channel |
دردسترس نیست. از legacy_local فقط برای محصولات محلی استفاده کنید. |
فیلد channel دیگر در Merchant API وجود ندارد. محصولات دارای کانال LOCAL در Content API for Shopping باید درعوض فیلد legacy_local را روی true تنظیم کنند. |
| دردسترس نیست | versionNumber |
فیلد اختیاری جدیدی در ProductInput که می‌توان از آن برای جلوگیری از درج‌های نامرتب در منابع داده اصلی استفاده کرد. |
فیلدهای نوع string با مجموعه مقادیر تعریف‌شده |
فیلدهای نوع enum با مجموعه مقادیر تعریف‌شده |
فیلدهای درون مشخصه‌های محصول با مجموعه مقادیر تعریف‌شده (برای مثال excluded_destinations، availability) اکنون از نوع enum هستند. |
gtin |
productAttributes.gtins |
از رشته مفرد (gtin) به رشته تکراری (gtins) تغییر کرد. |
sizes |
productAttributes.size |
از رشته تکراری (sizes) به رشته مفرد (size) تغییر کرد. |
sizeType، additionalSizeType |
productAttributes.sizeTypes |
sizeType و additionalSizeType با یک enum تکراری SizeType (sizeTypes) جایگزین شده است که حداکثر دو مقدار را می‌پذیرد (برای مثال، ["PETITE", "MATERNITY"]). |