نقل المنتجات

تقدّم 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 الذي تمت معالجته.

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

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

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

ملاحظة: يمكنك تحسين معدّل النقل باستخدام مجموعات القنوات: يمكنك إعداد مجموعة قنوات لـ زيادة معدّل النقل إلى أقصى حد للعمليات المجمّعة. يؤدي ذلك إلى تجاوز الحدّ المعتاد البالغ 100 بث لقناة gRPC واحدة من خلال إدارة اتصالات أساسية متعددة. لمزيد من المعلومات، يُرجى الاطّلاع على إعادة هيكلة الرمز البرمجي للطلبات المتزامنة: تحسين سرعة معالجة البيانات باستخدام مجموعات القنوات

إرشادات مصدر البيانات أثناء نقل البيانات

المصطلح الرئيسي: يحدث "سرقة العرض" عندما يتم إدراج منتج محدّد بمفتاحه الفريد (language وfeedlabel وofferID) في مصدر بيانات أساسي مختلف عن المصدر الذي ينتمي إليه. يؤدي ذلك فعليًا إلى حذف المنتج من المصدر القديم ونقله إلى المصدر الجديد، حيث قد يتم تطبيق قواعد مختلفة لمصدر البيانات وإعدادات ملكية مختلفة. في حين يمكن استخدام السرقة عن قصد لإعادة تنظيم المنتجات، يمكن أن تحدث السرقة عن طريق الخطأ إذا تم تقديم dataSource غير صحيح أثناء الإدراج.

قبل نقل مصادر البيانات، ننصحك بشدة باختيار استراتيجية مصدر البيانات.

لضمان عملية نقل سلسة ومنع حدوث مشاكل مثل سرقة العرض، اتّبِع هذه التوصيات:

• إعادة ملء قاعدة البيانات: بدلاً من استدعاء dataSources.list قبل كل عملية منتج، ننصحك بشدة بإجراء عملية إعادة ملء لمرة واحدة لقاعدة البيانات المحلية. أضِف حقل اسم dataSource إلى كل سجلّ منتج حتى تتمكّن من تقديم المعرّف الصحيح مباشرةً في طلباتك.

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

• حماية منتجاتك: إذا كنت تستخدم قواعد مصدر البيانات، استدعِ products.get للعثور على dataSource الدقيق المرتبط بمنتج قبل تعديله أو حذفه. يضمن ذلك تعديل المصدر المقصود ويمنع سرقة العرض عن طريق الخطأ.

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

الطلبات

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

وصف الطلب	Content API for 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 إلى اسم مورد RESTful عادي.

وصف المعرّف	Content API for Shopping	Merchant API
معرّف المنتج	سلسلة مؤلّفة من أجزاء مفصولة بنقطتَين رأسيتَين (:). التنسيق: channel:contentLanguage:targetCountry:offerId أو channel:contentLanguage:feedLabel:offerId. مثال: online:en:US:sku123	سلسلة name لمورد RESTful. التنسيق: accounts/{account}/products/{product} حيث {product} هو contentLanguage~feedLabel~offerId. مثال: accounts/12345/products/en~US~sku123. الترميز: يُنصح باستخدام ترميز base64url غير المضمّن وهو إلزامي في حال احتواء معرّفات المنتجات على أحرف تستخدمها Merchant API أو أحرف محجوزة في عناوين URL.

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

الطُرق

يعرض هذا الجدول طُرق 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.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	Merchant API	الوصف
id	name	المعرّف الأساسي للمنتج هو الآن name لمورد RESTful. يُنصح باستخدام ترميز 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. يجب بدلاً من ذلك ضبط الحقل legacy_local على "صحيح" للمنتجات التي تتضمّن القناة LOCAL في Content API for Shopping.
غير متوفر	versionNumber	حقل اختياري جديد في ProductInput يمكن استخدامه لمنع عمليات الإدراج غير المنظّمة في مصادر البيانات الأساسية.
حقول من النوع string تتضمّن مجموعة محدّدة من القيم	حقول من النوع enum تتضمّن مجموعة محدّدة من القيم	أصبحت الحقول ضمن سمات المنتج التي تتضمّن مجموعة محدّدة من القيم (مثل excluded_destinations وavailability) الآن من النوع enum.