نقل المنتجات

توفّر Merchant API طريقة أكثر فعالية وسهولة لإدارة بيانات منتجاتك. التغيير الرئيسي هو فصل بيانات المنتجات إلى مرجعَين مختلفَين: ProductInput لإرسال بياناتك وProduct لعرض النسخة النهائية المعالَجة التي تتضمّن حالة المنتج والمشاكل. ويوفّر هذا الهيكل الجديد تجربة أكثر قابلية للتوقّع وشفافية.

يرشدك هذا الدليل إلى الاختلافات الرئيسية لمساعدتك في نقل عملية الدمج من Content API for Shopping. للحصول على دليل تفصيلي حول استخدام الميزات الجديدة، اطّلِع على إدارة منتجاتك.

الاختلافات الرئيسية

في ما يلي أهم التغييرات على طريقة إدارة المنتجات في Merchant API مقارنةً بواجهة Content API for Shopping:

• موارد مخصّصة للبيانات المدخلة والمعالَجة: تقسّم Merchant API إدارة المنتجات إلى موردَين. يمكنك استخدام مورد ProductInput لإدراج بيانات منتجاتك وتعديلها وحذفها. يمكنك استخدام مورد Product للقراءة فقط للاطّلاع على المنتج النهائي بعد أن يعالج محرّك بحث Google المدخلات ويطبّق القواعد ويجمع البيانات من مصادر تكميلية.

• الترميز لأسماء المنتجات: يمكنك استخدام ترميز base64url غير المضمّن (القسم 5 من RFC 4648) لكل من الحقلين ProductInput.name وProduct.name. في حال كانت أسماء المنتجات تتضمّن أحرفًا تستخدمها Merchant API أو أحرفًا محجوزة في عناوين URL، يكون الترميز إلزاميًا. على سبيل المثال، يجب ترميز أسماء المنتجات إذا كانت تحتوي على أي من الأحرف التالية:

  % . + / : ~ , ( * ! ) & ? = @ # $
  

• حالة المنتج المدمج: تتم إزالة خدمة "productstatuses". تمّت الآن إضافة مشاكل التحقّق من صحة المنتجات وحالات الوجهات مباشرةً إلى المورد Product ضمن الحقل productStatus، ما يسهّل عملية استرداد البيانات.

• تعديلات متوقّعة على المنتجات: تعدّل الطريقة الجديدة productInputs.patch إدخال منتج معيّن مباشرةً. وهذا تحسّن كبير مقارنةً بـ Content API for Shopping، حيث كان من الممكن أن يتم بشكل غير متوقّع استبدال التعديلات بعمليات تحميل أخرى للخلاصة. في Merchant API، يبقى التعديل ساريًا إلى أن يتم تعديل بيانات المنتج المحدّد مرة أخرى أو حذفها. يتم تطبيق تحديثات المنتجات على المورد ProductInput بدلاً من المورد Product الذي تمت معالجته.

• اختيار مصدر البيانات لإدارة البيانات بشكل أكثر فعالية: تتطلّب جميع عمليات الكتابة الآن مَعلمة طلب بحث dataSource، ما يوضّح مصدر البيانات الذي يتم تعديله.productInputs ويكون ذلك مفيدًا بشكل خاص إذا كان لديك مصادر متعددة تقدّم البيانات.

• معرّفات الموارد الجديدة: يتم الآن تحديد المنتجات من خلال مورد RESTful name بدلاً من الحقل id. التنسيق هو accounts/{account}/products/{product}.

• ما مِن دفعات مخصّصة: لم تعُد طريقة custombatch متاحة. يمكنك استخدام الطلبات غير المتزامنة أو تجميع طلبات HTTP لإرسال طلبات متعدّدة في طلب HTTP واحد.

• مصادر البيانات لأي تصنيف خلاصة ولغة: تتيح Merchant API إنشاء مصدر بيانات بدون تحديد تصنيف الخلاصة واللغة، وبالتالي تسمح بإدراج منتج بأي تصنيف خلاصة ولغة.

ملاحظة: احرص على استخدام offerId نفسه للمنتج نفسه عند طلب بيانات من Merchant API كما فعلت مع Content API for Shopping لتجنُّب فقدان سجلّ منتجك. يمكنك أيضًا الاطّلاع على قسم المعرّفات في هذه الصفحة.

الطلبات

يقارن هذا القسم بين أشكال الطلبات في Content API for Shopping وMerchant API.

وصف الطلب	واجهة برمجة تطبيقات المحتوى في Shopping	Merchant API
الحصول على منتج	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 عادي.

وصف المعرّف	واجهة برمجة تطبيقات المحتوى في Shopping	Merchant API
معرّف المنتج	سلسلة تتألف من أجزاء مفصولة بنقطتين (:). التنسيق: 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 أو أحرف محجوزة في عناوين URL.

ملاحظة: لم يعُد الحقل channel متوفّرًا في Merchant API. بالنسبة إلى المنتجات التي تتضمّن القناة LOCAL في Content API for Shopping، يجب بدلاً من ذلك ضبط الحقل legacy_local على "صحيح".

الطُرق

يعرض هذا الجدول طرق Content API for Shopping وما يعادلها في Merchant API.

طريقة Content API for Shopping	طريقة Merchant API	التوفّر والملاحظات
products.get	products.get	يسترد هذا الحقل المنتج النهائي الذي تمت معالجته.
products.list	products.list	تعرض هذه السمة المنتجات النهائية التي تمت معالجتها.
products.insert	productInputs.insert	تُدرج هذه السمة حقل إدخال منتج. يتطلّب هذا الإجراء الاشتراك في dataSource.
products.update	productInputs.update	ويختلف السلوك بشكلٍ كبير. تعدّل هذه السمة إدخال منتج معيّن وتكون ثابتة.
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.

واجهة برمجة تطبيقات المحتوى في Shopping	Merchant API	الوصف
id	name	المعرّف الأساسي للمنتج هو الآن مورد REST name. يُنصح باستخدام ترميز base64url بدون إضافة مساحة وهو إلزامي في حال كانت أسماء المنتجات تحتوي على أحرف تستخدمها Merchant API أو أحرف محجوزة في عناوين URL.
سمات مواصفات بيانات المنتج ذات المستوى الأعلى (مثل title، price، link)	productAttributes عنصر	لم تعُد سمات المنتج، مثل title وprice وlink، حقولاً على المستوى الأعلى. يتم الآن تجميعها ضمن العنصر productAttributes في كل من الموردَين Product وProductInput. يوفّر ذلك بنية موارد أكثر وضوحًا وتنظيمًا.
targetCountry	feedLabel	يستخدم اسم المرجع الآن feedLabel بدلاً من targetCountry ليتوافق مع وظائف Merchant Center.
feedId	dataSource (مَعلمة طلب البحث)	أصبح اسم dataSource الآن مَعلمة طلب بحث مطلوبة لجميع طرق الكتابة في productInputs (insert وupdate وdelete).
channel	هذه الميزة غير متوفّرة. استخدِم القيمة legacy_local للمنتجات المتوفّرة في المتجر فقط.	لم يعُد الحقل channel متوفّرًا في Merchant API. بالنسبة إلى المنتجات التي تتضمّن القناة LOCAL في Content API for Shopping، يجب بدلاً من ذلك ضبط الحقل legacy_local على "صحيح".
غير متوفر	versionNumber	حقل اختياري جديد في ProductInput يمكن استخدامه لمنع عمليات الإدراج غير المنظَّمة في مصادر البيانات الأساسية.
حقول من النوع string مع مجموعة محدّدة من القيم	حقول من النوع enum مع مجموعة محدّدة من القيم	أصبحت الحقول ضمن سمات المنتجات التي تتضمّن مجموعة محدّدة من القيم (مثل excluded_destinations وavailability) من النوع enum.