نقل المنتجات

توفّر 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 واحد.

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

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

مصطلح رئيسي: تحدث "سرقة العرض" عندما يتم إدراج منتج تم تحديده من خلال مفتاحه الفريد (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.

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

الطُرق

يعرض هذا الجدول طرق 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.

واجهة برمجة تطبيقات المحتوى في 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.
gtin	productAttributes.gtins	تم التغيير من سلسلة مفردة (gtin) إلى سلسلة متكرّرة (gtins).
sizes	productAttributes.size	تم التغيير من سلسلة متكرّرة (sizes) إلى سلسلة مفردة (size).
‫sizeType، additionalSizeType	productAttributes.sizeTypes	تم استبدال sizeType وadditionalSizeType بتعداد SizeType متكرّر (sizeTypes) يقبل ما يصل إلى قيمتَين (على سبيل المثال، ["PETITE", "MATERNITY"]).